Aplicar ComputeClasses aos pods por predefinição

Este documento mostra como aplicar ComputeClasses por predefinição aos pods do Google Kubernetes Engine (GKE) que não selecionam explicitamente uma ComputeClass. Esta página tem instruções para definir uma ComputeClass como predefinição num espaço de nomes e para um cluster completo. Este documento destina-se a administradores de clusters que pretendem reduzir a sobrecarga manual causada pela configuração individual da carga de trabalho e do nó.

Já deve estar familiarizado com as ComputeClasses personalizadas.

Acerca das ComputeClasses predefinidas

Pode configurar clusters do GKE ou espaços de nomes específicos para terem uma ComputeClass predefinida. A classe predefinida que configurar aplica-se a qualquer Pod nesse cluster ou espaço de nomes que não selecione uma ComputeClass diferente. Quando implementa um pod que não seleciona uma ComputeClass, o GKE aplica as ComputeClasses predefinidas pela seguinte ordem:

  1. Se o espaço de nomes tiver uma ComputeClass predefinida, o GKE modifica a especificação do pod para selecionar essa ComputeClass.
  2. Se o espaço de nomes não tiver uma ComputeClass predefinida, é aplicada a classe predefinida ao nível do cluster. O GKE não modifica a especificação do pod.

Quando define uma ComputeClass predefinida para um cluster ou um espaço de nomes, a alteração aplica-se apenas a novos pods. Os Pods existentes não são afetados até serem recriados. Este comportamento aplica-se mesmo que a sua ComputeClass tenha a migração ativa.

Se o seu ComputeClass predefinido tiver o campo activeMigration.optimizeRulePriority definido como true, esta definição pode afetar as cargas de trabalho nos seus clusters. Para mais informações, consulte o artigo Migração ativa nas ComputeClasses predefinidas.

Antes de começar

Antes de começar, certifique-se de que realizou as seguintes tarefas:

  • Ative a API Google Kubernetes Engine.
    • Ative a API Google Kubernetes Engine
  • Se quiser usar a CLI gcloud para esta tarefa, instale-a e, em seguida, inicialize a CLI gcloud. Se instalou anteriormente a CLI gcloud, execute o comando gcloud components update para obter a versão mais recente. As versões anteriores da CLI gcloud podem não suportar a execução dos comandos neste documento.
  • Ter um cluster do GKE Autopilot ou Standard que execute uma versão que suporte a definição de uma ComputeClass predefinida ao nível do cluster ou do espaço de nomes. Para mais informações, consulte a secção Requisitos.

  • Se estiver a usar um cluster do modo padrão, certifique-se de que cumpre um dos seguintes requisitos:

  • Se quiser definir uma ComputeClass personalizada como predefinição para um espaço de nomes, implemente uma ComputeClass personalizada.

Requisitos

  • Para definir uma ComputeClass como predefinição ao nível do cluster, o cluster tem de executar a versão 1.33.1-gke.1744000 ou posterior do GKE.
  • Para definir uma ComputeClass como predefinição ao nível do espaço de nomes apenas para pods não DaemonSet, o cluster tem de executar a versão 1.33.1-gke.1788000 ou posterior do GKE.

Funções e autorizações necessárias

Para receber as autorizações de que precisa para configurar ComputeClasses predefinidas ao nível do cluster ou do espaço de nomes, peça ao seu administrador para lhe conceder as seguintes funções de IAM no Google Cloud projeto:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Estas funções predefinidas contêm as autorizações necessárias para configurar ComputeClasses predefinidas ao nível do cluster ou do espaço de nomes. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para configurar ComputeClasses predefinidas ao nível do cluster ou do espaço de nomes:

  • 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
  • Adicione etiquetas a espaços de nomes: container.namespaces.update
  • Ative a ComputeClass predefinida ao nível do cluster: container.clusters.update

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Configure uma ComputeClass predefinida para um espaço de nomes

Pode anotar qualquer espaço de nomes do Kubernetes no seu cluster com o nome de uma ComputeClass para usar como predefinição. Se um Pod implementado nesse espaço de nomes ainda não selecionar uma ComputeClass, o GKE modifica a especificação do Pod para selecionar a classe predefinida no espaço de nomes. Pode predefinir qualquer ComputeClass personalizado ou integrado.

  • Para aplicar uma ComputeClass a todos os pods num espaço de nomes por predefinição, adicione a etiqueta cloud.google.com/default-compute-class a esse espaço de nomes:

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

    Substitua o seguinte:

    • NAMESPACE_NAME: o nome do espaço de nomes a atualizar.
    • COMPUTECLASS_NAME: o nome da ComputeClass a definir como predefinição para o espaço de nomes.

    Se o comando falhar com a seguinte mensagem de erro, o espaço de nomes já tem uma ComputeClass predefinida:

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

    Para resolver este erro, atualize a ComputeClass predefinida para o espaço de nomes.

  • Para aplicar uma ComputeClass a todos os pods não DaemonSet num espaço de nomes por predefinição, adicione a etiqueta cloud.google.com/default-compute-class-non-daemonset a esse espaço de nomes:

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

    Se o comando falhar com a seguinte mensagem de erro, o espaço de nomes já tem uma ComputeClass predefinida para pods que não sejam DaemonSet:

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

    Para resolver este erro, atualize a ComputeClass predefinida para o espaço de nomes.

As suas alterações aplicam-se a todos os novos pods nesse espaço de nomes. Os Pods existentes não são afetados.

Atualize a ComputeClass predefinida existente num espaço de nomes

Para substituir a ComputeClass predefinida existente de um espaço de nomes, execute um dos seguintes comandos:

  • Atualize a ComputeClass predefinida para todos os pods no espaço de nomes:

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

    Substitua o seguinte:

    • NAMESPACE_NAME: o nome do espaço de nomes a atualizar.
    • COMPUTECLASS_NAME: o nome da ComputeClass a definir como a nova predefinição para o espaço de nomes.

  • Substitua a ComputeClass predefinida para pods que não sejam DaemonSet no espaço de nomes:

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

Configure uma ComputeClass predefinida para espaços de nomes do sistema

O GKE usa namespaces do sistema para executar várias cargas de trabalho geridas, como agentes de monitorização. Algumas destas cargas de trabalho geridas são DaemonSets, que têm de ser executadas em todos os nós do cluster para oferecerem funcionalidades críticas. No entanto, pode especificar uma ComputeClass predefinida para pods que não sejam DaemonSet em espaços de nomes do sistema, para que esses pods sejam executados separadamente das suas cargas de trabalho.

Para definir uma ComputeClass predefinida para espaços de nomes do sistema, siga estes passos:

  1. Guarde o seguinte script como apply-system-cc.sh. Este script permite-lhe aplicar uma ComputeClass recomendada ou a sua própria ComputeClass existente a espaços de nomes do 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."

    Este script usa a etiqueta cloud.google.com/default-compute-class-non-daemonset, que afeta apenas os pods não DaemonSet nos espaços de nomes do sistema.

  2. Execute o script:

    ./apply-system-cc.sh

Após a conclusão do script, todos os novos pods do sistema não DaemonSet usam a ComputeClass especificada por predefinição, a menos que já tenham uma ComputeClass. Os pods existentes nesses espaços de nomes não são afetados. Se o GKE adicionar novos espaços de nomes do sistema, execute este script novamente para aplicar alterações a esses espaços de nomes.

Para anular a definição da ComputeClass predefinida para espaços de nomes do sistema, siga estes passos:

  1. Guarde o seguinte script 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. Execute o script:

    ./unset-system-cc.sh

Configure uma classe de computação predefinida para um cluster

Esta secção mostra como definir uma ComputeClass como predefinição para o seu cluster. Para ComputeClasses predefinidas ao nível do cluster, não especifique manualmente taints de nós nem etiquetas de nós para node pools existentes no cluster. O GKE não dimensiona pools de nós que tenham taints de nós para ComputeClasses. Se adicionar manualmente uma etiqueta para o ComputeClass default, o GKE pode dimensionar esse conjunto de nós. No entanto, esta configuração manual não é necessária para usar uma classe de computação predefinida ao nível do cluster.

  1. Para ativar a definição de uma ComputeClass predefinida ao nível do cluster para um cluster, execute o comando gcloud container clusters update com a flag --enable-default-compute-class:

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

    Substitua o seguinte:

    • CLUSTER_NAME: o nome do seu cluster.
    • CONTROL_PLANE_LOCATION: a localização do seu plano de controlo do cluster, como us-central1.

    Também pode especificar esta flag quando cria um cluster do Autopilot ou Standard.

  2. Guarde o seguinte manifesto, que define um ComputeClass com o nome default:

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

    Este manifesto de exemplo pede nós que usam instâncias N4. Se as instâncias N4 não estiverem disponíveis, o ComputeClass pede instâncias N2. Pode configurar a default ComputeClass com qualquer um dos campos disponíveis na ComputeClass CustomResourceDefinition.

  3. Aplique o manifesto ao cluster:

    kubectl apply -f PATH_TO_MANIFEST

    Substitua PATH_TO_MANIFEST pelo caminho para o manifesto da ComputeClass.

Depois de definir uma ComputeClass predefinida ao nível do cluster, o GKE dimensiona os conjuntos de nós que cumprem os seguintes requisitos:

  • A configuração do nó é igual à configuração da default ComputeClass.
  • O conjunto de nós não tem restrições nem etiquetas para uma ComputeClass diferente. O GKE pode dimensionar pools de nós que tenham uma mancha e uma etiqueta para a default ComputeClass.

Por exemplo, se a default ComputeClass especificar a série de máquinas N4, o GKE pode dimensionar um pool de nós existente que use instâncias N4 e não tenha taints nem etiquetas para uma ComputeClass diferente.

As alterações aplicam-se a todos os novos pods no cluster que ainda não tenham uma ComputeClass. Os pods existentes podem ser afetados consoante as definições de migração ativas da ComputeClass predefinida ao nível do cluster. Para mais informações, consulte o artigo Migração ativa nas ComputeClasses predefinidas.

Valide o comportamento predefinido de ComputeClass

Para verificar se a ComputeClass predefinida que definiu para um espaço de nomes ou para um cluster funciona como esperado, faça o seguinte:

  1. Reveja o exemplo de implementação seguinte:

    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 implementação não pede explicitamente uma ComputeClass.

  2. Crie a implementação:

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

    Substitua NAMESPACE_NAME por uma das seguintes opções, consoante o que quer validar:

    • O nome de um espaço de nomes que tem uma ComputeClass predefinida.
    • O nome de um espaço de nomes que não tem uma ComputeClass predefinida.

    O GKE pode demorar algum tempo a criar novos nós para executar os pods.

  3. Identifique os nós que executam os pods da implementação de exemplo:

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

    O resultado é semelhante ao seguinte:

    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. Obtenha as etiquetas dos nós:

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

    Substitua NODE_NAME pelo nome do nó da saída do passo anterior.

    O resultado é semelhante ao seguinte:

    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

    O valor em COMPUTECLASS_NAME é um dos seguintes:

    • ComputeClass predefinida ao nível do cluster: default para nós criados pelo GKE Autopilot ou pela criação automática de node pools. Os nós em conjuntos de nós criados manualmente existentes podem não ter a etiqueta cloud.google.com/compute-class.
    • ComputeClass predefinida ao nível do espaço de nomes: o nome da ComputeClass que configurou como predefinição do espaço de nomes.

Desative a ComputeClass predefinida

Para desativar a ComputeClass predefinida num espaço de nomes ou num cluster, faça o seguinte:

  • Para desativar a ComputeClass predefinida ao nível do espaço de nomes para todos os pods, remova a etiqueta cloud.google.com/default-compute-class do espaço de nomes:

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

    O caráter - no final da chave da etiqueta remove todas as etiquetas com essa chave do objeto Namespace na API Kubernetes.

  • Para desativar a ComputeClass predefinida ao nível do espaço de nomes para pods que não sejam DaemonSet, remova a etiqueta cloud.google.com/default-compute-class-non-daemonset do espaço de nomes:

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

  • Para desativar a ComputeClass predefinida ao nível do cluster, use o comando gcloud container clusters update com a flag --no-enable-default-compute-class:

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

O que se segue?