Aplica ComputeClasses a los Pods de forma predeterminada

En este documento, se muestra cómo aplicar ComputeClasses de forma predeterminada a los Pods de Google Kubernetes Engine (GKE) que no seleccionan una ComputeClass de forma explícita. En esta página, se incluyen instrucciones para establecer una ComputeClass como predeterminada en un espacio de nombres y para todo un clúster. Este documento está dirigido a los administradores de clústeres que desean reducir la sobrecarga manual causada por la configuración individual de nodos y cargas de trabajo.

Ya deberías conocer las ComputeClasses personalizadas.

Acerca de las ComputeClasses predeterminadas

Puedes configurar clústeres de GKE o espacios de nombres específicos para que tengan una ComputeClass predeterminada. La clase predeterminada que configures se aplica a cualquier Pod en ese clúster o espacio de nombres que no seleccione una ComputeClass diferente. Cuando implementas un Pod que no selecciona un ComputeClass, GKE aplica ComputeClasses predeterminados en el siguiente orden:

  1. Si el espacio de nombres tiene una ComputeClass predeterminada, GKE modifica la especificación del Pod para seleccionar esa ComputeClass.
  2. Si el espacio de nombres no tiene un ComputeClass predeterminado, se aplica la clase predeterminada a nivel del clúster. GKE no modifica la especificación del Pod.

Cuando estableces una ComputeClass predeterminada para un clúster o un espacio de nombres, el cambio se aplica solo a los Pods nuevos. Los Pods existentes no se ven afectados hasta que se vuelven a crear. Este comportamiento se aplica incluso si tu ComputeClass tiene habilitada la migración activa.

Si tu ComputeClass predeterminada tiene el campo activeMigration.optimizeRulePriority establecido en true, este parámetro de configuración podría afectar las cargas de trabajo en tus clústeres. Para obtener más información, consulta Migración activa en ComputeClasses predeterminadas.

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

  • Habilita la API de Google Kubernetes Engine.
    • Habilitar la API de Google Kubernetes Engine
  • Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste gcloud CLI, ejecuta el comando gcloud components update para obtener la versión más reciente. Es posible que las versiones anteriores de gcloud CLI no admitan la ejecución de los comandos que se describen en este documento.
  • Tener un clúster de GKE Autopilot o Standard que ejecute una versión que admita la configuración de un ComputeClass predeterminado a nivel del clúster o del espacio de nombres Para obtener más información, consulta la sección Requisitos.

  • Si usas un clúster de modo Standard, asegúrate de cumplir con uno de los siguientes requisitos:

  • Si deseas establecer una ComputeClass personalizada como la predeterminada para un espacio de nombres, implementa una ComputeClass personalizada.

Requisitos

  • Para establecer un ComputeClass como valor predeterminado a nivel del clúster, este debe ejecutar la versión 1.33.1-gke.1744000 de GKE o una posterior.
  • Para establecer un ComputeClass como valor predeterminado a nivel del espacio de nombres solo para Pods que no sean DaemonSet, el clúster debe ejecutar la versión 1.33.1-gke.1788000 de GKE o una versión posterior.

Roles y permisos requeridos

Para obtener los permisos que necesitas para configurar ComputeClasses predeterminadas a nivel del clúster o del espacio de nombres, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto Google Cloud :

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para configurar ComputeClasses predeterminadas a nivel del clúster o del espacio de nombres. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para configurar ComputeClasses predeterminadas a nivel del clúster o del espacio de nombres:

  • container.customResourceDefinitions.create
  • container.customResourceDefinitions.update
  • container.customResourceDefinitions.get
  • container.customResourceDefinitions.list
  • container.namespaces.get
  • container.namespaces.list
  • container.pods.get
  • container.nodes.get
  • container.nodes.list
  • container.deployments.create
  • container.deployments.get
  • Agrega etiquetas a los espacios de nombres: container.namespaces.update
  • Habilita la ComputeClass predeterminada a nivel del clúster: container.clusters.update

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Configura una ComputeClass predeterminada para un espacio de nombres

Puedes anotar cualquier espacio de nombres de Kubernetes en tu clúster con el nombre de un ComputeClass para usarlo como predeterminado. Si un Pod implementado en ese espacio de nombres aún no selecciona una ComputeClass, GKE modifica la especificación del Pod para seleccionar la clase predeterminada en el espacio de nombres. Puedes establecer cualquier ComputeClass personalizada o integrada como predeterminada.

  • Para aplicar un ComputeClass a todos los Pods de un espacio de nombres de forma predeterminada, agrega la etiqueta cloud.google.com/default-compute-class a ese espacio de nombres:

    kubectl label namespaces NAMESPACE_NAME \
    cloud.google.com/default-compute-class=COMPUTECLASS_NAME

    Reemplaza lo siguiente:

    • NAMESPACE_NAME: Es el nombre del espacio de nombres que se actualizará.
    • COMPUTECLASS_NAME: Es el nombre de la ComputeClass que se establecerá como predeterminada para el espacio de nombres.

    Si el comando falla con el siguiente mensaje de error, el espacio de nombres ya tiene un ComputeClass predeterminado:

    error: 'cloud.google.com/default-compute-class' already has a value, and --overwrite is false

    Para resolver este error, actualiza la ComputeClass predeterminada para el espacio de nombres.

  • Para aplicar un ComputeClass a todos los Pods que no son de DaemonSet en un espacio de nombres de forma predeterminada, agrega la etiqueta cloud.google.com/default-compute-class-non-daemonset a ese espacio de nombres:

    kubectl label namespaces NAMESPACE_NAME \
    cloud.google.com/default-compute-class-non-daemonset=COMPUTECLASS_NAME

    Si el comando falla con el siguiente mensaje de error, significa que el espacio de nombres ya tiene un ComputeClass predeterminado para los Pods que no son de DaemonSet:

    error: 'cloud.google.com/default-compute-class-non-daemonset' already has a value, and --overwrite is false

    Para resolver este error, actualiza la ComputeClass predeterminada para el espacio de nombres.

Los cambios se aplican a todos los Pods nuevos en ese espacio de nombres. Los Pods existentes no se ven afectados.

Actualiza la ComputeClass predeterminada existente en un espacio de nombres

Para anular la ComputeClass predeterminada existente para un espacio de nombres, ejecuta uno de los siguientes comandos:

  • Actualiza la ComputeClass predeterminada para todos los Pods en el espacio de nombres:

    kubectl label namespaces NAMESPACE_NAME   \
    cloud.google.com/default-compute-class=COMPUTECLASS_NAME \
    --overwrite

    Reemplaza lo siguiente:

    • NAMESPACE_NAME: Es el nombre del espacio de nombres que se actualizará.
    • COMPUTECLASS_NAME: Es el nombre de la ComputeClass que se establecerá como la nueva predeterminada para el espacio de nombres.

  • Anula la ComputeClass predeterminada para los Pods que no son de DaemonSet en el espacio de nombres:

    kubectl label namespaces NAMESPACE_NAME \
    cloud.google.com/default-compute-class-non-daemonset=COMPUTECLASS_NAME \
    --overwrite

Configura una ComputeClass predeterminada para los espacios de nombres del sistema

GKE usa espacios de nombres del sistema para ejecutar varias cargas de trabajo administradas, como los agentes de supervisión. Algunas de estas cargas de trabajo administradas son DaemonSets, que deben ejecutarse en cada nodo del clúster para proporcionar funcionalidad crítica. Sin embargo, puedes especificar un ComputeClass predeterminado para los Pods que no son DaemonSet en los espacios de nombres del sistema, de modo que esos Pods se ejecuten por separado de tus cargas de trabajo.

Para establecer un valor predeterminado de ComputeClass para los espacios de nombres del sistema, sigue estos pasos:

  1. Guarda la siguiente secuencia de comandos como apply-system-cc.sh. Este script te permite aplicar una ComputeClass recomendada o tu propia ComputeClass existente a los espacios de nombres del sistema.

    #!/bin/bash

# The recommended default ComputeClass name for system pods.
DEFAULT_SYSTEM_CC_NAME="system-default-computeclass"

# The YAML manifest for the recommended default ComputeClass for system pods.
read -r -d '' DEFAULT_CC_YAML << EOF
apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: ${DEFAULT_SYSTEM_CC_NAME}
spec:
  nodePoolAutoCreation:
    enabled: true
  whenUnsatisfiable: ScaleUpAnyway
  priorities:
  - machineFamily: t2d
EOF

# The label key to apply to namespaces.
LABEL_KEY="cloud.google.com/default-compute-class-non-daemonset"


# List of GKE system namespaces.
SYSTEM_NAMESPACES=(
  "kube-system"
  "gke-gmp-system"
  "gmp-system"
  "gke-managed-cim"
  "gke-managed-volumepopulator"
  "gke-managed-checkpointing"
  "gkebackup"
  "gke-managed-lustrecsi"
)


# 1. Ask the user for their choice.
echo "This script sets a default ComputeClass for GKE system namespaces."
echo "--------------------------------------------------------------------"
echo "The following ComputeClass is recommended for system Pods:"
echo ""
echo "$DEFAULT_CC_YAML"
echo "--------------------------------------------------------------------"
read -p "Do you want to use the recommended ComputeClass? (y/N): " user_choice

CC_TO_APPLY=""

# 2. Process the user's choice.
if [[ "$user_choice" =~ ^[Yy]$ ]]; then
  # Path 1: User chose YES.
  echo "Installing the recommended default ComputeClass '${DEFAULT_SYSTEM_CC_NAME}'..."

  if ! echo "$DEFAULT_CC_YAML" | kubectl apply -f -; then
      # If kubectl apply fails, print an error and exit.
      echo "❌ Error: Failed to create the default ComputeClass. An internal error occurred."
      echo "Check for kubectl permissions or other cluster issues and re-run the script."
      exit 1
  fi
  # If the command succeeded, set the name to be used for labeling.
  CC_TO_APPLY="$DEFAULT_SYSTEM_CC_NAME"

else
  read -p "Specify the name of an existing ComputeClass to set as the default for system Pods: " custom_cc_name

  # Validate that the user entered a name.
  while [[ -z "$custom_cc_name" ]]; do
    echo "Error: Name cannot be empty."
    read -p "Specify the name of an existing ComputeClass: " custom_cc_name
  done

  # Check if the specified ComputeClass actually exists in the cluster.
  echo "--> Verifying that ComputeClass '${custom_cc_name}' exists..."
  if kubectl get computeclass "$custom_cc_name" > /dev/null 2>&1; then
    echo "Verified."
    CC_TO_APPLY="$custom_cc_name"
  else
    echo "Error: ComputeClass '${custom_cc_name}' doesn't exist in the cluster."
    echo "Create the ComputeClass, and then then re-run this script."
    exit 1
  fi
fi

echo ""
echo "Labelling system namespaces with ComputeClass: '${CC_TO_APPLY}'"
echo "--------------------------------------------------------------------"

# 3. Apply the label to all system namespaces.
for ns in "${SYSTEM_NAMESPACES[@]}"; do
  # Gracefully handle namespaces that don't exist on this specific cluster.
  if kubectl get namespace "${ns}" > /dev/null 2>&1; then
    echo "--> Applying label to namespace: ${ns}"
    kubectl label namespace "${ns}" \
      "${LABEL_KEY}=${CC_TO_APPLY}" --overwrite
  else
    echo "--> Skipping namespace ${ns} (does not exist)"
  fi
done

echo ""
echo "✅ Script finished successfully."

    Esta secuencia de comandos usa la etiqueta cloud.google.com/default-compute-class-non-daemonset, que solo afecta a los Pods que no son de DaemonSet en los espacios de nombres del sistema.

  2. Ejecuta la secuencia de comandos:

    ./apply-system-cc.sh

Una vez que se complete la secuencia de comandos, todos los Pods del sistema nuevos que no sean de DaemonSet usarán la ComputeClass especificada de forma predeterminada, a menos que ya tengan una. Los Pods existentes en esos espacios de nombres no se ven afectados. Si GKE agrega nuevos espacios de nombres del sistema, vuelve a ejecutar esta secuencia de comandos para aplicar los cambios a esos espacios de nombres.

Para anular la configuración de ComputeClass predeterminada para los espacios de nombres del sistema, sigue estos pasos:

  1. Guarda la siguiente secuencia de comandos como unset-system-cc.sh:

    #!/bin/bash

# The recommended default ComputeClass name for system pods.
DEFAULT_SYSTEM_CC_NAME="system-default-computeclass"

# The YAML manifest for the recommended default ComputeClass for system pods.
read -r -d '' DEFAULT_CC_YAML << EOF
apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: ${DEFAULT_SYSTEM_CC_NAME}
spec:
  nodePoolAutoCreation:
    enabled: true
  whenUnsatisfiable: ScaleUpAnyway
  priorities:
  - machineFamily: t2d
EOF

# The label key to apply to namespaces.
LABEL_KEY="cloud.google.com/default-compute-class-non-daemonset"


# List of GKE system namespaces.
SYSTEM_NAMESPACES=(
  "kube-system"
  "gke-gmp-system"
  "gmp-system"
  "gke-managed-cim"
  "gke-managed-volumepopulator"
  "gke-managed-checkpointing"
  "gkebackup"
  "gke-managed-lustrecsi"
)


# 1. Ask the user for their choice.
echo "This script sets a default ComputeClass for GKE system namespaces."
echo "--------------------------------------------------------------------"
echo "The following ComputeClass is recommended for system Pods:"
echo ""
echo "$DEFAULT_CC_YAML"
echo "--------------------------------------------------------------------"
read -p "Do you want to use the recommended ComputeClass? (y/N): " user_choice

CC_TO_APPLY=""

# 2. Process the user's choice.
if [[ "$user_choice" =~ ^[Yy]$ ]]; then
  # Path 1: User chose YES.
  echo "Installing the recommended default ComputeClass '${DEFAULT_SYSTEM_CC_NAME}'..."

  if ! echo "$DEFAULT_CC_YAML" | kubectl apply -f -; then
      # If kubectl apply fails, print an error and exit.
      echo "❌ Error: Failed to create the default ComputeClass. An internal error occurred."
      echo "Check for kubectl permissions or other cluster issues and re-run the script."
      exit 1
  fi
  # If the command succeeded, set the name to be used for labeling.
  CC_TO_APPLY="$DEFAULT_SYSTEM_CC_NAME"

else
  read -p "Specify the name of an existing ComputeClass to set as the default for system Pods: " custom_cc_name

  # Validate that the user entered a name.
  while [[ -z "$custom_cc_name" ]]; do
    echo "Error: Name cannot be empty."
    read -p "Specify the name of an existing ComputeClass: " custom_cc_name
  done

  # Check if the specified ComputeClass actually exists in the cluster.
  echo "--> Verifying that ComputeClass '${custom_cc_name}' exists..."
  if kubectl get computeclass "$custom_cc_name" > /dev/null 2>&1; then
    echo "Verified."
    CC_TO_APPLY="$custom_cc_name"
  else
    echo "Error: ComputeClass '${custom_cc_name}' doesn't exist in the cluster."
    echo "Create the ComputeClass, and then then re-run this script."
    exit 1
  fi
fi

echo ""
echo "Labelling system namespaces with ComputeClass: '${CC_TO_APPLY}'"
echo "--------------------------------------------------------------------"

# 3. Apply the label to all system namespaces.
for ns in "${SYSTEM_NAMESPACES[@]}"; do
  # Gracefully handle namespaces that don't exist on this specific cluster.
  if kubectl get namespace "${ns}" > /dev/null 2>&1; then
    echo "--> Applying label to namespace: ${ns}"
    kubectl label namespace "${ns}" \
      "${LABEL_KEY}=${CC_TO_APPLY}" --overwrite
  else
    echo "--> Skipping namespace ${ns} (does not exist)"
  fi
done

echo ""
echo "✅ Script finished successfully."

  2. Ejecuta la secuencia de comandos:

    ./unset-system-cc.sh

Configura una clase de procesamiento predeterminada para un clúster

En esta sección, se muestra cómo establecer una ComputeClass como la predeterminada para tu clúster. En el caso de las ComputeClasses predeterminadas a nivel del clúster, no especifiques manualmente taints ni etiquetas de nodos para los grupos de nodos existentes en el clúster. GKE no ajusta la escala de los grupos de nodos que tienen taints de nodos para ComputeClasses. Si agregas manualmente una etiqueta para default ComputeClass, GKE puede escalar ese grupo de nodos. Sin embargo, esta configuración manual no es necesaria para usar una clase de procesamiento predeterminada a nivel del clúster.

  1. Para habilitar la configuración de un valor predeterminado de ComputeClass a nivel del clúster, ejecuta el comando gcloud container clusters update con la marca --enable-default-compute-class:

    gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-default-compute-class

    Reemplaza lo siguiente:

    • CLUSTER_NAME: El nombre de tu clúster.
    • CONTROL_PLANE_LOCATION: Es la ubicación del plano de control del clúster, como us-central1.

    También puedes especificar esta marca cuando creas un clúster de Autopilot o Standard.

  2. Guarda el siguiente manifiesto, que define un ComputeClass llamado default:

    apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: default
spec:
  priorities:
  - machineFamily: n4
  - machineFamily: n2
  whenUnsatisfiable: ScaleUpAnyway
  nodePoolAutoCreation:
    enabled: true

    En este manifiesto de ejemplo, se solicitan nodos que usan instancias N4. Si las instancias de N4 no están disponibles, ComputeClass solicita instancias de N2. Puedes configurar el default ComputeClass con cualquiera de los campos disponibles en la CustomResourceDefinition de ComputeClass.

  3. Aplica el manifiesto al clúster:

    kubectl apply -f PATH_TO_MANIFEST

    Reemplaza PATH_TO_MANIFEST por la ruta de acceso al manifiesto de ComputeClass.

Después de establecer un valor predeterminado de ComputeClass a nivel del clúster, GKE ajusta la escala de los grupos de nodos que cumplen con los siguientes requisitos:

  • La configuración del nodo es la misma que la configuración de defaultComputeClass.
  • El grupo de nodos no tiene marcas ni etiquetas para una ComputeClass diferente. GKE puede escalar grupos de nodos que tienen un taint y una etiqueta para la ComputeClass default.

Por ejemplo, si la clase de procesamiento default especifica la serie de máquinas N4, GKE puede ajustar la escala de un grupo de nodos existente que use instancias N4 y no tenga marcas o etiquetas para una clase de procesamiento diferente.

Los cambios se aplican a todos los Pods nuevos del clúster que aún no tienen una ComputeClass. Es posible que los Pods existentes se vean afectados según la configuración de migración activa de la ComputeClass predeterminada a nivel del clúster. Para obtener más información, consulta Migración activa en ComputeClasses predeterminadas.

Verifica el comportamiento predeterminado de ComputeClass

Para verificar si la ComputeClass predeterminada que estableciste para un espacio de nombres o un clúster funciona según lo esperado, haz lo siguiente:

  1. Revisa el siguiente ejemplo de Deployment:

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: helloweb
  labels:
    app: hello
spec:
  selector:
    matchLabels:
      app: hello
      tier: web
  template:
    metadata:
      labels:
        app: hello
        tier: web
    spec:
      containers:
      - name: hello-app
        image: us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0
        ports:
        - containerPort: 8080
        resources:
          requests:
            cpu: 200m

    Esta implementación no solicita explícitamente una ComputeClass.

  2. Crea el Deployment:

    kubectl apply --namespace=NAMESPACE_NAME \
    -f https://raw.githubusercontent.com/GoogleCloudPlatform/kubernetes-engine-samples/refs/heads/main/quickstarts/hello-app/manifests/helloweb-deployment.yaml

    Reemplaza NAMESPACE_NAME por uno de los siguientes valores, según lo que quieras verificar:

    • Es el nombre de un espacio de nombres que tiene una ComputeClass predeterminada.
    • Es el nombre de un espacio de nombres que no tiene un ComputeClass predeterminado.

    Es posible que GKE tarde en crear nodos nuevos para ejecutar los Pods.

  3. Identifica los nodos que ejecutan los Pods de la Deployment de ejemplo:

    kubectl get pods --namespace=NAMESPACE_NAME \
    --selector=app=hello -o=wide

    El resultado es similar a lo siguiente:

    NAME                        READY   STATUS    RESTARTS   AGE     IP          NODE                                                  NOMINATED NODE   READINESS GATES
helloweb-7795fbf856-58n5l   1/1     Running   0          9m21s   10.52.2.3   gke-cluster-1-nap-n2-highcpu-2-3muqi8-f213e529-rx7d   <none>           <none>

  4. Obtén las etiquetas del nodo:

    kubectl get node NODE_NAME --show-labels \
    | grep "cloud.google.com/compute-class"

    Reemplaza NODE_NAME por el nombre del nodo del resultado del paso anterior.

    El resultado es similar a lo siguiente:

    NODE_NAME   Ready    <none>   22m   v1.32.4-gke.1236007
# lines are omitted from this output
cloud.google.com/compute-class=COMPUTECLASS_NAME,cloud.google.com/gke-boot-disk=pd-balanced,cloud.google.com/gke-container-runtime=containerd

    El valor en COMPUTECLASS_NAME es uno de los siguientes:

    • ComputeClass predeterminada a nivel del clúster: default para los nodos que creó GKE Autopilot o la creación automática de grupos de nodos. Es posible que los nodos de los grupos de nodos existentes creados de forma manual no tengan la etiqueta cloud.google.com/compute-class.
    • ComputeClass predeterminada a nivel del espacio de nombres: Es el nombre de la ComputeClass que configuraste como predeterminada para el espacio de nombres.

Inhabilita la ComputeClass predeterminada

Para inhabilitar la ComputeClass predeterminada en un espacio de nombres o un clúster, realiza una de las siguientes acciones:

  • Para inhabilitar la ComputeClass predeterminada a nivel del espacio de nombres para todos los Pods, quita la etiqueta cloud.google.com/default-compute-class del espacio de nombres:

    kubectl label namespaces NAMESPACE_NAME \
  cloud.google.com/default-compute-class-

    El carácter - al final de la clave de la etiqueta quita todas las etiquetas con esa clave del objeto Namespace en la API de Kubernetes.

  • Para inhabilitar la ComputeClass predeterminada a nivel del espacio de nombres para los Pods que no son de DaemonSet, quita la etiqueta cloud.google.com/default-compute-class-non-daemonset del espacio de nombres:

    kubectl label namespaces NAMESPACE_NAME \
  cloud.google.com/default-compute-class-non-daemonset-

  • Para inhabilitar la ComputeClass predeterminada a nivel del clúster, usa el comando gcloud container clusters update con la marca --no-enable-default-compute-class:

    gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --no-enable-default-compute-class

¿Qué sigue?