Applica ComputeClasses ai pod per impostazione predefinita

Questo documento mostra come applicare ComputeClass per impostazione predefinita ai pod Google Kubernetes Engine (GKE) che non selezionano esplicitamente una ComputeClass. Questa pagina contiene le istruzioni per impostare una ComputeClass come predefinita in un namespace e per un intero cluster. Questo documento è destinato agli amministratori di cluster che vogliono ridurre l'overhead manuale causato dalla configurazione dei singoli nodi e carichi di lavoro.

Dovresti già avere familiarità con le ComputeClass personalizzate.

Informazioni su ComputeClass predefinite

Puoi configurare i cluster GKE o spazi dei nomi specifici in modo che abbiano una ComputeClass predefinita. La classe predefinita che configuri si applica a qualsiasi pod nel cluster o nello spazio dei nomi che non seleziona una ComputeClass diversa. Quando esegui il deployment di un pod che non seleziona una ComputeClass, GKE applica le ComputeClass predefinite nel seguente ordine:

  1. Se lo spazio dei nomi ha un oggetto ComputeClass predefinito, GKE modifica la specifica del pod per selezionare ComputeClass.
  2. Se lo spazio dei nomi non ha una ComputeClass predefinita, viene applicata la classe predefinita a livello di cluster. GKE non modifica la specifica del pod.

Quando imposti una ComputeClass predefinita per un cluster o uno spazio dei nomi, la modifica viene applicata solo ai nuovi pod. I pod esistenti non sono interessati finché non vengono ricreati. Questo comportamento si applica anche se la migrazione attiva è abilitata per ComputeClass.

Se il campo activeMigration.optimizeRulePriority della tua ComputeClass predefinita è impostato su true, questa impostazione potrebbe influire sui carichi di lavoro nei tuoi cluster. Per maggiori informazioni, vedi Migrazione attiva in ComputeClasses predefinite.

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti operazioni:

  • Attiva l'API Google Kubernetes Engine.
    • Attiva l'API Google Kubernetes Engine
  • Se vuoi utilizzare Google Cloud CLI per questa attività, installala e poi inizializza gcloud CLI. Se hai già installato gcloud CLI, scarica l'ultima versione eseguendo il comando gcloud components update. Le versioni precedenti di gcloud CLI potrebbero non supportare l'esecuzione dei comandi in questo documento.

Requisiti

  • Per impostare una ComputeClass come predefinita a livello di cluster, il cluster deve eseguire GKE versione 1.33.1-gke.1744000 o successive.
  • Per impostare una ComputeClass come predefinita a livello di spazio dei nomi solo per i pod non DaemonSet, il cluster deve eseguire GKE versione 1.33.1-gke.1788000 o successive.

Ruoli e autorizzazioni richiesti

Per ottenere le autorizzazioni necessarie per configurare ComputeClass predefinite a livello di cluster o spazio dei nomi, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto Google Cloud :

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per configurare ComputeClass predefinite a livello di cluster o spazio dei nomi. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per configurare le ComputeClass predefinite a livello di cluster o spazio dei nomi sono necessarie le seguenti autorizzazioni:

  • 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
  • Aggiungi etichette agli spazi dei nomi: container.namespaces.update
  • Abilita la classe di computing predefinita a livello di cluster: container.clusters.update

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Configura una risorsa ComputeClass predefinita per uno spazio dei nomi

Puoi annotare qualsiasi spazio dei nomi Kubernetes nel tuo cluster con il nome di una ComputeClass da utilizzare come predefinita. Se un pod di cui è stato eseguito il deployment in questo spazio dei nomi non seleziona già una ComputeClass, GKE modifica la specifica del pod per selezionare la classe predefinita nello spazio dei nomi. Puoi impostare qualsiasi ComputeClass personalizzata o integrata come predefinita.

  • Per applicare una ComputeClass a tutti i pod in uno spazio dei nomi per impostazione predefinita, aggiungi l'etichetta cloud.google.com/default-compute-class a questo spazio dei nomi:

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

    Sostituisci quanto segue:

    • NAMESPACE_NAME: il nome dello spazio dei nomi da aggiornare.
    • COMPUTECLASS_NAME: il nome di ComputeClass da impostare come predefinita per lo spazio dei nomi.

    Se il comando non va a buon fine e viene visualizzato il seguente messaggio di errore, lo spazio dei nomi ha già una ComputeClass predefinita:

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

    Per risolvere questo errore, aggiorna ComputeClass predefinita per lo spazio dei nomi.

  • Per applicare una ComputeClass a tutti i pod non DaemonSet in uno spazio dei nomi per impostazione predefinita, aggiungi l'etichetta cloud.google.com/default-compute-class-non-daemonset a questo spazio dei nomi:

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

    Se il comando non va a buon fine e viene visualizzato il seguente messaggio di errore, lo spazio dei nomi ha già una ComputeClass predefinita per i pod non DaemonSet:

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

    Per risolvere questo errore, aggiorna ComputeClass predefinita per lo spazio dei nomi.

Le modifiche si applicano a tutti i nuovi pod in quello spazio dei nomi. I Pod esistenti non sono interessati.

Aggiorna la ComputeClass predefinita esistente in uno spazio dei nomi

Per sovrascrivere la ComputeClass predefinita esistente per uno spazio dei nomi, esegui uno dei seguenti comandi:

  • Aggiorna ComputeClass predefinita per tutti i pod nello spazio dei nomi:

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

    Sostituisci quanto segue:

    • NAMESPACE_NAME: il nome dello spazio dei nomi da aggiornare.
    • COMPUTECLASS_NAME: il nome di ComputeClass da impostare come nuovo valore predefinito per lo spazio dei nomi.

  • Sovrascrivi la ComputeClass predefinita per i pod non DaemonSet nello spazio dei nomi:

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

Configura una ComputeClass predefinita per gli spazi dei nomi di sistema

GKE utilizza gli spazi dei nomi di sistema per eseguire vari workload gestiti, ad esempio gli agenti di monitoraggio. Alcuni di questi workload gestiti sono DaemonSet, che devono essere eseguiti su ogni nodo del cluster per fornire funzionalità critiche. Tuttavia, puoi specificare una ComputeClass predefinita per i pod non DaemonSet negli spazi dei nomi di sistema, in modo che questi pod vengano eseguiti separatamente dai tuoi carichi di lavoro.

Per impostare un ComputeClass predefinito per gli spazi dei nomi di sistema:

  1. Salva il seguente script come apply-system-cc.sh. Questo script ti consente di applicare una ComputeClass consigliata o una ComputeClass esistente agli spazi dei nomi di 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."

    Questo script utilizza l'etichetta cloud.google.com/default-compute-class-non-daemonset, che influisce solo sui pod non DaemonSet negli spazi dei nomi di sistema.

  2. Esegui lo script:

    ./apply-system-cc.sh

Al termine dello script, tutti i nuovi pod di sistema non DaemonSet utilizzano la ComputeClass specificata per impostazione predefinita, a meno che non ne abbiano già una. I pod esistenti in questi spazi dei nomi non sono interessati. Se GKE aggiunge nuovi spazi dei nomi di sistema, esegui di nuovo questo script per applicare le modifiche a questi spazi dei nomi.

Per annullare l'impostazione di ComputeClass predefinita per gli spazi dei nomi di sistema:

  1. Salva il seguente script come 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. Esegui lo script:

    ./unset-system-cc.sh

Configura una classe di computing predefinita per un cluster

Questa sezione mostra come impostare una ComputeClass come predefinita per il cluster. Per le ComputeClass predefinite a livello di cluster, non specificare manualmente i taint dei nodi e le etichette dei nodi per i node pool esistenti nel cluster. GKE non esegue lo scale dei node pool con taint dei nodi per ComputeClass. Se aggiungi manualmente un'etichetta per default ComputeClass, GKE può scalare il pool di nodi. Tuttavia, questa configurazione manuale non è necessaria per utilizzare una classe di calcolo predefinita a livello di cluster.

  1. Per abilitare l'impostazione di una ComputeClass predefinita a livello di cluster per un cluster, esegui il comando gcloud container clusters update con il flag --enable-default-compute-class:

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

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del tuo cluster.
    • CONTROL_PLANE_LOCATION: la posizione del control plane del cluster, ad esempio us-central1.

    Puoi specificare questo flag anche quando crei un cluster Autopilot o Standard.

  2. Salva il seguente manifest, che definisce un ComputeClass denominato default:

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

    Questo manifest di esempio richiede nodi che utilizzano istanze N4. Se le istanze N4 non sono disponibili, ComputeClass richiede istanze N2. Puoi configurare default ComputeClass con uno qualsiasi dei campi disponibili nella CustomResourceDefinition di ComputeClass.

  3. Applica il manifest al cluster:

    kubectl apply -f PATH_TO_MANIFEST

    Sostituisci PATH_TO_MANIFEST con il percorso del manifest per ComputeClass.

Dopo aver impostato una ComputeClass predefinita a livello di cluster, GKE scala i node pool che soddisfano entrambi i seguenti requisiti:

  • La configurazione del nodo è la stessa della configurazione di default ComputeClass.
  • Il pool di nodi non ha taint o etichette per una ComputeClass diversa. GKE può scalare i pool di nodi con un taint e un'etichetta per la default ComputeClass.

Ad esempio, se default ComputeClass specifica la serie di macchine N4, GKE può scalare un pool di nodi esistente che utilizza istanze N4 e non ha taint o etichette per una ComputeClass diversa.

Le modifiche vengono applicate a tutti i nuovi pod nel cluster che non hanno già una ComputeClass. I pod esistenti potrebbero essere interessati a seconda delle impostazioni di migrazione attive della ComputeClass predefinita a livello di cluster. Per maggiori informazioni, vedi Migrazione attiva in ComputeClasses predefinite.

Verifica il comportamento predefinito di ComputeClass

Per verificare se la ComputeClass predefinita che hai impostato per uno spazio dei nomi o per un cluster funziona come previsto, procedi nel seguente modo:

  1. Esamina il seguente esempio di 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

    Questo deployment non richiede esplicitamente una ComputeClass.

  2. Crea il 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

    Sostituisci NAMESPACE_NAME con uno dei seguenti valori, a seconda di ciò che vuoi verificare:

    • Il nome di uno spazio dei nomi con una ComputeClass predefinita.
    • Il nome di uno spazio dei nomi che non ha una ComputeClass predefinita.

    GKE potrebbe impiegare un po' di tempo per creare nuovi nodi per eseguire i pod.

  3. Identifica i nodi che eseguono i pod del deployment di esempio:

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

    L'output è simile al seguente:

    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. Recupera le etichette del nodo:

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

    Sostituisci NODE_NAME con il nome del nodo dall'output del passaggio precedente.

    L'output è simile al seguente:

    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

    Il valore in COMPUTECLASS_NAME è uno dei seguenti:

    • ComputeClass predefinita a livello di cluster: default per i nodi creati da GKE Autopilot o dalla creazione automatica del pool di nodi. I nodi nei pool di nodi esistenti creati manualmente potrebbero non avere l'etichetta cloud.google.com/compute-class.
    • ComputeClass predefinita a livello di spazio dei nomi: il nome di ComputeClass che hai configurato come predefinita per lo spazio dei nomi.

Disattiva ComputeClass predefinita

Per disattivare ComputeClass predefinita in uno spazio dei nomi o in un cluster, esegui una delle seguenti operazioni:

  • Per disattivare la ComputeClass predefinita a livello di spazio dei nomi per tutti i pod, rimuovi l'etichetta cloud.google.com/default-compute-class dallo spazio dei nomi:

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

    Il carattere - alla fine della chiave dell'etichetta rimuove tutte le etichette con quella chiave dall'oggetto Namespace nell'API Kubernetes.

  • Per disattivare la ComputeClass predefinita a livello di spazio dei nomi per i pod non DaemonSet, rimuovi l'etichetta cloud.google.com/default-compute-class-non-daemonset dallo spazio dei nomi:

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

  • Per disattivare ComputeClass predefinita a livello di cluster, utilizza il comando gcloud container clusters update con il flag --no-enable-default-compute-class:

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

Passaggi successivi