Soluciona problemas de cargas de trabajo implementadas

Autopilot Estándar

---

En esta página, se muestra cómo resolver errores con tus cargas de trabajo implementadas en Google Kubernetes Engine (GKE).

Para obtener más consejos generales sobre la solución de problemas de tus aplicaciones, consulta Cómo solucionar problemas de aplicaciones en la documentación de Kubernetes.

Todos los errores: Verifica el estado del Pod

Si hay problemas con los Pods de una carga de trabajo, Kubernetes actualiza el estado del Pod con un mensaje de error. Para ver estos errores, verifica el estado de un Pod con la consola de Google Cloud o la herramienta de línea de comandos de kubectl.

Console

Sigue los siguientes pasos:

1. En la consola de Google Cloud , ve a la página Cargas de trabajo.

   Ir a Cargas de trabajo

2. Elige la carga de trabajo que deseas investigar. La pestaña Descripción general muestra el estado de la carga de trabajo.

3. En la sección Pods administrados, haz clic en un mensaje de estado de error.

kubectl

Para ver todos los pods en ejecución en tu clúster, ejecuta el comando siguiente:

kubectl get pods

El resultado es similar a este:

NAME       READY  STATUS             RESTARTS  AGE
POD_NAME   0/1    CrashLoopBackOff   23        8d

Los posibles errores se indican en la columna Status.

Para obtener más información sobre un pod específico, ejecuta el siguiente comando:

kubectl describe pod POD_NAME

Reemplaza POD_NAME por el nombre del Pod que deseas investigar.

En el resultado, el campo Events muestra más información sobre los errores.

Si quieres obtener más información, consulta los registros del contenedor:

kubectl logs POD_NAME

Estos registros pueden ayudarte a identificar si un comando o código en el contenedor hizo que el Pod fallara.

Después de identificar el error, usa las siguientes secciones para intentar resolver el problema.

Error: CrashLoopBackOff

Un estado de CrashLoopBackOff no significa que haya un error específico, sino que indica que un contenedor falla repetidas veces después de reiniciarse. Cuando un contenedor falla o se cierra poco después de iniciarse (CrashLoop), Kubernetes intenta reiniciarlo. Con cada reinicio que falla, el retraso (BackOff) antes del siguiente intento aumenta de forma exponencial (10 s, 20 s, 40 s, etcétera), hasta un máximo de cinco minutos.

En las siguientes secciones, se explica por qué es posible que tu contenedor falle.

Usa la guía interactiva de Pods con fallas

Para comenzar a solucionar el problema que causa un estado CrashLoopBackOff, usa la guía interactiva en la consola de Google Cloud :

1. Ve a la guía interactiva de Pods en un bucle de fallas:

   Ir a la guía

2. En la lista desplegable Clúster, selecciona el clúster para el que deseas solucionar el problema. Si no encuentras tu clúster, ingresa su nombre en el campo Filtro de .

3. En la lista desplegable Espacio de nombres, selecciona el espacio de nombres para el que deseas solucionar el problema. Si no encuentras tu espacio de nombres, ingrésalo en el campo Filtro de .

4. Revisa cada una de las secciones para ayudarte a identificar la causa:

   1. Identifica los errores de la aplicación
   2. Investiga los problemas de memoria insuficiente
   3. Investiga las interrupciones del nodo
   4. Investiga las fallas de los sondeos en funcionamiento
   5. Correlaciona los eventos de cambio

5. Opcional: Para recibir notificaciones sobre errores CrashLoopBackOff futuros, en la sección Sugerencias para mitigaciones futuras, selecciona Crear una alerta.

Inspecciona registros

Un contenedor puede fallar por varias razones y verificar los registros de un Pod puede ayudar a solucionar la causa del problema.

Puedes verificar los registros con la consola de Google Cloud o la herramienta de línea de comandos de kubectl.

Console

Sigue los siguientes pasos:

1. Ve a la página Cargas de trabajo en la consola de Google Cloud .

   Ir a Cargas de trabajo

2. Elige la carga de trabajo que deseas investigar. La pestaña Descripción general muestra el estado de la carga de trabajo.

3. En la sección Pods administrados, haz clic en el pod problemático.

4. En el menú de pods, haz clic en la pestaña Registros.

kubectl

1. Visualiza todos los Pods que se ejecutan en tu clúster:

   kubectl get pods
   

2. En el resultado del comando anterior, busca un Pod con el error CrashLoopBackOff en la columna Status.

3. Obtén los registros del Pod:

   kubectl logs POD_NAME
   

   Reemplaza POD_NAME con el nombre del pod problemático.

   También puedes pasar la marca -p para obtener los registros de la instancia anterior del contenedor de un Pod, si existe.

Verifica el código de salida del contenedor que falla

Para comprender mejor por qué falló tu contenedor, busca el código de salida:

1. Describe el Pod:

   kubectl describe pod POD_NAME
   

   Reemplaza POD_NAME con el nombre del pod problemático.

2. Revisa el valor en el campo containers: CONTAINER_NAME: last state: exit code:

   • Si el código de salida es 1, el contenedor falló debido a que la aplicación falló.
   • Si el código de salida es 0, verifica por cuánto tiempo se ejecutó la app. Los contenedores se detienen cuando el proceso principal de la aplicación se detiene. Si la app finaliza la ejecución muy rápido, el contendor se puede reiniciar. Si experimentas este error, una solución es establecer el campo restartPolicy en OnFailure. Después de realizar este cambio, la app solo se reinicia cuando el código de salida no es 0.

Conéctate a un contenedor en ejecución

Para ejecutar comandos bash desde el contenedor de modo que puedas probar la red o verificar si tienes acceso a los archivos o a las bases de datos que usa tu aplicación, abre un shell en el Pod:

kubectl exec -it POD_NAME -- /bin/bash

Si hay más de un contenedor en tu Pod, agrega -c CONTAINER_NAME.

Errores: ImagePullBackOff y ErrImagePull

Un estado de ImagePullBackOff o ErrImagePull indica que la imagen que usa un contenedor no se puede cargar desde el registro de imágenes.

Puedes verificar este problema con la consola de Google Cloud o la herramienta de línea de comandos de kubectl.

Console

Sigue los siguientes pasos:

1. En la consola de Google Cloud , ve a la página Cargas de trabajo.

   Ir a Cargas de trabajo

2. Elige la carga de trabajo que deseas investigar. La pestaña Descripción general muestra el estado de la carga de trabajo.

3. En la sección Pods administrados, haz clic en el pod problemático.

4. En el menú de pod, haz clic en la pestaña Eventos.

kubectl

Para obtener más información sobre una imagen de contenedor de un Pod, ejecuta el comando siguiente:

kubectl describe pod POD_NAME

Problema: No se encontró la imagen

Si no se encuentra tu imagen, completa los siguientes pasos:

1. Verifica que el nombre de la imagen sea correcto.
2. Verifica que la etiqueta de la imagen sea correcta. (Prueba :latest o sin etiqueta para extraer la imagen más reciente).
3. Si la imagen tiene una ruta de registro completa, verifica que exista en el registro Docker que usas. Si proporcionas solo el nombre de la imagen, verifica el registro de Docker Hub.

4. En los clústeres de GKE Standard, intenta extraer la imagen de Docker de manera manual:

   1. Usa SSH para conectarte a la VM.

      Por ejemplo, para usar SSH y conectarte a una VM, ejecuta el siguiente comando:

      gcloud compute ssh VM_NAME --zone=ZONE_NAME
      

      Reemplaza lo siguiente:

      • VM_NAME: el nombre de la VM.
      • ZONE_NAME: una zona de Compute Engine

   2. Genera un archivo de configuración en /home/[USER]/.docker/config.json:

      docker-credential-gcr configure-docker
      

      Asegúrate de que el archivo de configuración en /home/[USER]/.docker/config.json incluya el registro de la imagen en el campo credHelpers. Por ejemplo, el siguiente archivo incluye información de autenticación para las imágenes alojadas en asia.gcr.io, eu.gcr.io, gcr.io, marketplace.gcr.io y us.gcr.io:

      {
      "auths": {},
      "credHelpers": {
        "asia.gcr.io": "gcr",
        "eu.gcr.io": "gcr",
        "gcr.io": "gcr",
        "marketplace.gcr.io": "gcr",
        "us.gcr.io": "gcr"
      }
      }
      

   3. Intenta extraer la imagen:

      docker pull IMAGE_NAME
      

   Si extraer la imagen de forma manual funciona, es probable que debas especificar ImagePullSecrets en un Pod. Los Pods solo pueden hacer referencia a los Secrets de extracción de imagen en su propio espacio de nombres, por lo que este proceso puede realizarse una vez por espacio de nombres.

Error: Permiso denegado

Si encuentras el error “permiso denegado” o “sin acceso de extracción”, verifica que accediste y tienes acceso a la imagen. Prueba uno de los siguientes métodos según el registro en el que alojas tus imágenes.

Precaución: Container Registry está obsoleto y se programó para el cierre. Las organizaciones que no usaron Container Registry antes del 8 de enero de 2024 tendrán nuevos repositorios de gcr.io alojados en Artifact Registry de forma predeterminada. A partir del 15 de mayo de 2024, los proyectos de Google Cloud sin uso anterior de Container Registry solo admitirán el hosting y la administración de imágenes para el dominio gcr.io en Artifact Registry.

Container Registry está programado para cerrarse el 18 de marzo de 2025. Para obtener detalles sobre la baja, consulta Baja de Container Registry.

Artifact Registry

Si la imagen está en Artifact Registry, la cuenta de servicio del grupo de nodos necesita acceso de lectura al repositorio que contiene la imagen.

Otorga el rol artifactregistry.reader a la cuenta de servicio:

gcloud artifacts repositories add-iam-policy-binding REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
    --role="roles/artifactregistry.reader"

Reemplaza lo siguiente:

• REPOSITORY_NAME: Es el nombre de tu repositorio de Artifact Registry.
• REPOSITORY_LOCATION: Es la región de tu repositorio de Artifact Registry.
• SERVICE_ACCOUNT_EMAIL: La dirección de correo electrónico de la cuenta de servicio de IAM asociada con tu grupo de nodos.

Container Registry

Si la imagen está en Container Registry, la cuenta de servicio del grupo de nodos necesita acceso de lectura al bucket de Cloud Storage que contiene la imagen.

Otorga el rol roles/storage.objectViewer a la cuenta de servicio para que pueda leer desde el bucket:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
    --role=roles/storage.objectViewer

Reemplaza lo siguiente:

• SERVICE_ACCOUNT_EMAIL: El correo electrónico de la cuenta de servicio asociada con tu grupo de nodos. Puedes enumerar todas las cuentas de servicio en tu proyecto mediante gcloud iam service-accounts list.
• BUCKET_NAME: es el nombre del bucket de Cloud Storage que contiene tus imágenes. Puedes enumerar todos los buckets de tu proyecto con gcloud storage ls.

Si tu administrador de registros configuró repositorios de gcr.io en Artifact Registry para almacenar imágenes del dominio gcr.io en lugar de Container Registry, debes otorgar acceso de lectura a Artifact Registry en lugar de Container Registry.

Registro privado

Si la imagen está en un registro privado, es posible que necesites claves para acceder a las imágenes. Para obtener más información, consulta Cómo usar registros privados en la documentación de Kubernetes.

Error 401 Sin autorización: No se pueden extraer imágenes del repositorio de Container Registry privado

Un error similar al siguiente puede ocurrir cuando extraes una imagen de un repositorio de Container Registry privado:

gcr.io/PROJECT_ID/IMAGE:TAG: rpc error: code = Unknown desc = failed to pull and
unpack image gcr.io/PROJECT_ID/IMAGE:TAG: failed to resolve reference
gcr.io/PROJECT_ID/IMAGE]:TAG: unexpected status code [manifests 1.0]: 401 Unauthorized

Warning  Failed     3m39s (x4 over 5m12s)  kubelet            Error: ErrImagePull
Warning  Failed     3m9s (x6 over 5m12s)   kubelet            Error: ImagePullBackOff
Normal   BackOff    2s (x18 over 5m12s)    kubelet            Back-off pulling image

Para resolver el error, completa los siguientes pasos:

1. Identifica el nodo que ejecuta el Pod:

   kubectl describe pod POD_NAME | grep "Node:"
   

2. Verifica que el nodo que identificaste en el paso anterior tenga el permiso de almacenamiento:

   gcloud compute instances describe NODE_NAME \
       --zone=COMPUTE_ZONE --format="flattened(serviceAccounts[].scopes)"
   

   El permiso de acceso del nodo debe contener al menos uno de los siguientes permisos:

   serviceAccounts[0].scopes[0]: https://www.googleapis.com/auth/devstorage.read_only
   serviceAccounts[0].scopes[0]: https://www.googleapis.com/auth/cloud-platform
   

   Si el nodo no contiene uno de estos permisos, vuelve a crear el grupo de nodos.

3. Vuelve a crear el grupo de nodos al que pertenece el nodo con permiso suficiente. No puedes modificar los nodos existentes, debes volver a crear el nodo con el permiso correcto.

   • Recomendado: Crea un grupo de nodos nuevo con el permiso gke-default:

     gcloud container node-pools create NODE_POOL_NAME \
         --cluster=CLUSTER_NAME \
         --zone=COMPUTE_ZONE \
         --scopes="gke-default"
     

   • Crea un grupo de nodos nuevo solo con el permiso de almacenamiento:

     gcloud container node-pools create NODE_POOL_NAME \
         --cluster=CLUSTER_NAME \
         --zone=COMPUTE_ZONE \
         --scopes="https://www.googleapis.com/auth/devstorage.read_only"
     

Error: Pod no programable

Un estado de PodUnschedulable indica que tu Pod no se puede programar debido a recursos insuficientes o a algún error de configuración.

Si configuraste las métricas del plano de control, puedes encontrar más información sobre estos errores en las métricas del programador y las métricas del servidor de la API.

Usa la guía interactiva de Pods no programables

Puedes solucionar los errores PodUnschedulable con la guía interactiva en la consola de Google Cloud :

1. Ve a la guía interactiva de Pods no programables:

   Ir a la guía

2. En la lista desplegable Clúster, selecciona el clúster para el que deseas solucionar el problema. Si no encuentras tu clúster, ingresa su nombre en el campo Filtro de .

3. En la lista desplegable Espacio de nombres, selecciona el espacio de nombres para el que deseas solucionar el problema. Si no encuentras tu espacio de nombres, ingrésalo en el campo Filtro de .

4. Para ayudarte a identificar la causa, revisa cada una de las secciones de la guía:

   1. Investiga la CPU y la memoria
   2. Investiga la cantidad máxima de Pods por nodo
   3. Investiga el comportamiento del escalador automático
   4. Investiga otros modos de falla
   5. Correlaciona los eventos de cambio

5. Opcional: Para recibir notificaciones sobre errores PodUnschedulable futuros, en la sección Sugerencias para mitigaciones futuras, selecciona Crear una alerta.

Error: Recursos insuficientes

Puedes encontrar un error que indique una falta de CPU, memoria o algún otro recurso. Por ejemplo: No nodes are available that match all of the predicates: Insufficient cpu (2), que indica que, en dos nodos, no hay suficiente CPU disponible para cumplir con las solicitudes de un Pod.

Si las solicitudes de recursos de tu pod superan las de un solo nodo de cualquier grupo de nodos apto, GKE no programa el pod ni activa el escalamiento vertical para agregar un nodo nuevo. Para que GKE programe el Pod, debes solicitar menos recursos para el Pod o crear un grupo de nodos nuevo con recursos suficientes.

También puedes habilitar el aprovisionamiento automático de nodos para que GKE pueda crear de forma automática grupos de nodos con nodos en los que puedan ejecutarse los Pods no programados.

La solicitud de CPU predeterminada es de 100m o el 10% de una CPU (o un núcleo). Si deseas solicitar más o menos recursos, detalla el valor en la especificación del Pod en spec: containers: resources: requests.

Nota: Tu clúster ejecuta contenedores de sistema en el espacio de nombres kube-system. Esos contenedores también usan recursos de clúster.

Error: MatchNodeSelector

MatchNodeSelector indica que no hay nodos que coincidan con el selector de etiquetas del pod.

Para verificar esto, revisa las etiquetas que se especifican en el campo nodeSelector de la especificación del pod, debajo de spec: nodeSelector.

Para ver cómo están etiquetados los nodos en tu clúster, ejecuta el siguiente comando:

kubectl get nodes --show-labels

Para adjuntar una etiqueta a un nodo, ejecuta el siguiente comando:

kubectl label nodes NODE_NAME LABEL_KEY=LABEL_VALUE

Reemplaza lo siguiente:

• NODE_NAME: Es el nodo al que deseas agregar una etiqueta.
• LABEL_KEY: la clave de la etiqueta.
• LABEL_VALUE: el valor de la etiqueta.

Para obtener más información, consulta Asigna Pods a nodos en la documentación de Kubernetes.

Error: PodToleratesNodeTaints

PodToleratesNodeTaints indica que el Pod no se puede programar en ningún nodo porque no tiene tolerancias que correspondan a los taints de nodo existentes.

Para verificar que este sea el caso, ejecuta el comando siguiente:

kubectl describe nodes NODE_NAME

En el resultado, verifica el campo Taints, que enumera pares clave-valor y efectos de programación.

Si el efecto enumerado es NoSchedule, entonces no se puede programar ningún pod en ese nodo, a menos que tenga una tolerancia coincidente.

Una manera de resolver este problema es quitar el taint. Por ejemplo, para quitar un taint NoSchedule, ejecuta el siguiente comando:

kubectl taint nodes NODE_NAME key:NoSchedule-

Error: PodFitsHostPorts

El error PodFitsHostPorts significa que un nodo intenta usar un puerto que ya está ocupado.

Para resolver el problema, considera seguir las prácticas recomendadas de Kubernetes y usa un NodePort en lugar de un hostPort.

Si debes usar un hostPort, verifica los manifiestos de los Pods y asegúrate de que todos los Pods del mismo nodo tengan valores únicos definidos para hostPort.

Error: No tiene disponibilidad mínima

Si un nodo tiene recursos adecuados, pero todavía ves el mensaje Does not have minimum availability, comprueba el estado del pod. Si el estado es SchedulingDisabled o Cordoned, el nodo no puede programar pods nuevos. Puedes verificar el estado de un nodo con la consola de Google Cloud o la herramienta de línea de comandos de kubectl.

Console

Sigue los siguientes pasos:

1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud .

   Ir a Google Kubernetes Engine

2. Selecciona el clúster que deseas explorar. La pestaña Nodos muestra los nodos y su estado.

Para habilitar la programación en el nodo, realiza los pasos siguientes:

1. En la lista, haz clic en el nodo que quieres investigar.

2. En la sección Detalles del nodo, haz clic en Desvincular.

kubectl

Para obtener los estados de los nodos, ejecuta el siguiente comando:

kubectl get nodes

Para habilitar la programación en el nodo, ejecuta lo siguiente:

kubectl uncordon NODE_NAME

Error: Se alcanzó el límite máximo de Pods por nodo

Si todos los nodos del clúster alcanzan el límite de máximo de Pods por nodo, los Pods se detendrán en estado no programable. En la pestaña Eventos del Pod, verás un mensaje que incluye la frase Too many pods.

Para resolver este error, completa los siguientes pasos:

1. Verifica la configuración de Maximum pods per node desde la pestaña Nodos en los detalles del clúster de GKE en la consola de Google Cloud .

2. Obtén una lista de nodos:

   kubectl get nodes
   

3. Para cada nodo, verifica la cantidad de Pods que se ejecutan en el nodo:

   kubectl get pods -o wide | grep NODE_NAME | wc -l
   

4. Si se alcanza el límite, agrega un grupo de nodos nuevo o agrega nodos adicionales al grupo existente.

Problema: Se alcanzó el tamaño máximo del grupo de nodos con el escalador automático del clúster habilitado

Si el grupo de nodos alcanzó su tamaño máximo según la configuración del escalador automático de clústeres, GKE no activa el escalamiento vertical para el Pod que, de lo contrario, se programaría con este grupo de nodos. Si quieres que el pod se programe con este grupo de nodos, cambia la configuración del escalador automático de clústeres.

Problema: Tamaño máximo del grupo de nodos alcanzado con el escalador automático del clúster inhabilitado

Si el grupo de nodos alcanzó la cantidad máxima de nodos y el escalador automático de clústeres está inhabilitado, GKE no puede programar el Pod con el grupo de nodos. Aumenta el tamaño de tu grupo de nodos o habilita el escalador automático del clúster para que GKE cambie el tamaño del clúster de forma automática.

Error: PersistentVolumeClaims no vinculados

Unbound PersistentVolumeClaims indica que el pod hace referencia a una PersistentVolumeClaim que no está vinculada. Este error puede ocurrir si no se pudo aprovisionar el PersistentVolume. Puedes verificar que el aprovisionamiento falló, si obtienes los eventos de la PersistentVolumeClaim y los examinas en busca de errores.

Para obtener los eventos, ejecuta el siguiente comando:

kubectl describe pvc STATEFULSET_NAME-PVC_NAME-0

Reemplaza lo siguiente:

• STATEFULSET_NAME: el nombre del objeto StatefulSet.
• PVC_NAME: el nombre del objeto PersistentVolumeClaim.

Esto también puede ocurrir si hubo un error de configuración durante el aprovisionamiento previo manual de un PersistentVolume y su vinculación a una PersistentVolumeClaim.

Para resolver este error, intenta aprovisionar el volumen de nuevo.

Error: Cuota insuficiente

Verifica que tu proyecto tenga suficiente cuota de Compute Engine para que GKE escale verticalmente tu clúster. Si GKE intenta agregar un nodo a tu clúster para programar el pod y escalar verticalmente superaría la cuota disponible de tu proyecto, recibirás el mensaje de error scale.up.error.quota.exceeded.

Para obtener más información, consulta Errores de ScaleUp.

Problema: APIs obsoletas

Asegúrate de no usar APIs obsoletas que se quitan con la versión secundaria de tu clúster. Para obtener más información, consulta Bajas de GKE.

Error: No había puertos libres para los puertos del pod solicitados

Si ves un error similar al siguiente, es probable que tengas varios pods en el mismo nodo con el mismo valor definido en el campo hostPort:

0/1 nodes are available: 1 node(s) didn't have free ports for the requested pod ports. preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod.

La vinculación de un Pod a un hostPort limita los lugares en los que GKE puede programarlo, ya que cada combinación de hostIP, hostPort y protocol debe ser única.

Para resolver el problema, considera seguir las prácticas recomendadas de Kubernetes y usar un NodePort en lugar de un hostPort.

Si debes usar un hostPort, verifica los manifiestos de los Pods y asegúrate de que todos los Pods del mismo nodo tengan valores únicos definidos para hostPort.

¿Qué sigue?

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