Aplicar ComputeClasses aos pods por padrão

Neste documento, mostramos como aplicar ComputeClasses por padrão aos pods do Google Kubernetes Engine (GKE) que não selecionam explicitamente uma ComputeClass. É possível definir uma ComputeClass como padrão para um namespace ou para um cluster inteiro. Este documento é destinado a administradores de cluster que querem reduzir a sobrecarga manual causada pela configuração individual da carga de trabalho e do nó.

Você já deve estar familiarizado com as ComputeClasses personalizadas.

Sobre as ComputeClasses padrão

É possível configurar clusters do GKE ou namespaces específicos para ter uma ComputeClass padrão. A classe padrão configurada se aplica a qualquer pod nesse cluster ou namespace que não selecione uma ComputeClass diferente. Ao implantar um pod que não seleciona uma ComputeClass, o GKE aplica as ComputeClasses padrão na seguinte ordem:

  1. Se o namespace tiver uma ComputeClass padrão, o GKE modificará a especificação do pod para selecionar essa ComputeClass.
  2. Se o namespace não tiver uma ComputeClass padrão, a classe padrão no nível do cluster será aplicada. O GKE não modifica a especificação do pod.

Quando você define uma ComputeClass padrão para um cluster ou um namespace, a mudança é aplicada apenas a novos pods. Os pods atuais não são afetados até serem recriados. Esse comportamento se aplica mesmo que a migração ativa esteja ativada na ComputeClass.

Se a ComputeClass padrão tiver o campo activeMigration.optimizeRulePriority definido como true, essa configuração poderá afetar as cargas de trabalho nos clusters. Para mais informações, consulte Migração ativa em ComputeClasses padrão.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

  • Ativar a API Google Kubernetes Engine.
    • Ativar a API Google Kubernetes Engine
  • Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.

Requisitos

  • Para definir uma ComputeClass como padrão no nível do cluster, o cluster precisa executar a versão 1.33.1-gke.1744000 ou mais recente do GKE.
  • Para definir uma ComputeClass como padrão no nível do namespace apenas para pods que não sejam do DaemonSet, o cluster precisa executar a versão 1.33.1-gke.1788000 ou mais recente do GKE.

Papéis e permissões necessárias

Para receber as permissões necessárias para configurar ComputeClasses padrão no nível do cluster ou do namespace, peça ao administrador para conceder a você os seguintes papéis do IAM no Cloud de Confiance projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para configurar ComputeClasses padrão no nível do cluster ou do namespace. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para configurar ComputeClasses padrão no nível do cluster ou do namespace:

  • 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
  • Adicionar rótulos a namespaces: container.namespaces.update
  • Ativar a ComputeClass padrão no nível do cluster: container.clusters.update

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Configurar uma ComputeClass padrão para um namespace

É possível anotar qualquer namespace do Kubernetes no cluster com o nome de uma ComputeClass a ser usada como padrão. Se um pod implantado nesse namespace ainda não selecionar uma ComputeClass, o GKE modificará a especificação do pod para selecionar a classe padrão no namespace. É possível definir qualquer ComputeClass personalizada ou integrada como padrão.

  • Para aplicar uma ComputeClass a todos os pods em um namespace por padrão, adicione o rótulo cloud.google.com/default-compute-class a esse namespace:

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

    Substitua:

    • NAMESPACE_NAME: o nome do namespace a ser atualizado.
    • COMPUTECLASS_NAME: o nome da ComputeClass a ser definida como padrão para o namespace.

    Se o comando falhar com a seguinte mensagem de erro, o namespace já terá uma ComputeClass padrão:

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

    Para resolver esse erro, atualize a ComputeClass padrão do namespace.

  • Para aplicar uma ComputeClass a todos os pods que não sejam do DaemonSet em um namespace por padrão, adicione o rótulo cloud.google.com/default-compute-class-non-daemonset a esse namespace:

    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 namespace já terá uma ComputeClass padrão para pods que não sejam do DaemonSet:

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

    Para resolver esse erro, atualize a ComputeClass padrão do namespace.

As mudanças serão aplicadas a todos os novos pods nesse namespace. Os pods atuais não são afetados.

Atualizar a ComputeClass padrão atual em um namespace

Para substituir a ComputeClass padrão atual de um namespace, execute um dos seguintes comandos:

  • Atualize a ComputeClass padrão para todos os pods no namespace:

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

    Substitua:

    • NAMESPACE_NAME: o nome do namespace a ser atualizado.
    • COMPUTECLASS_NAME: o nome da ComputeClass a ser definida como o novo padrão para o namespace.

  • Substitua a ComputeClass padrão para pods que não sejam do DaemonSet no namespace:

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

Configurar uma ComputeClass padrão para namespaces do sistema

O GKE usa namespaces do sistema para executar várias cargas de trabalho gerenciadas, como agentes de monitoramento. Algumas dessas cargas de trabalho gerenciadas são DaemonSets, que precisam ser executadas em todos os nós do cluster para fornecer funcionalidades críticas. No entanto, é possível especificar uma ComputeClass padrão para pods que não sejam do DaemonSet em namespaces do sistema, para que esses pods sejam executados separadamente das cargas de trabalho.

Para definir uma ComputeClass padrão para namespaces do sistema, siga estas etapas:

  1. Salve o script a seguir como apply-system-cc.sh. Esse script permite aplicar uma ComputeClass recomendada ou sua ComputeClass atual aos namespaces 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."

    Esse script usa o rótulo cloud.google.com/default-compute-class-non-daemonset, que afeta apenas pods que não sejam do DaemonSet em namespaces do sistema.

  2. Execute o script:

    ./apply-system-cc.sh

Depois que o script for concluído, todos os novos pods do sistema que não sejam do DaemonSet usarão a ComputeClass especificada por padrão, a menos que já tenham uma ComputeClass. Os pods atuais nesses namespaces não são afetados. Se o GKE adicionar novos namespaces do sistema, execute esse script novamente para aplicar mudanças a esses namespaces.

Para cancelar a definição da ComputeClass padrão para namespaces do sistema, siga estas etapas:

  1. Salve o script a seguir 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

Configurar uma ComputeClass padrão para um cluster

É possível definir qualquer ComputeClass personalizada como padrão para todo o cluster. Esse processo envolve a ativação de ComputeClasses padrão no nível do cluster e a criação de uma ComputeClass chamada default. É possível até mesmo receber o comportamento das ComputeClasses integradas do Autopilot especificando as mesmas regras de prioridade em uma ComputeClass chamada default.

É necessário realizar as duas etapas a seguir para usar corretamente uma ComputeClass padrão no cluster:

  1. Para ativar a definição de uma ComputeClass padrão no nível do cluster, use a --enable-default-compute-class flag ao criar ou atualizar um cluster:

    • Criar um cluster:

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

      Substitua:

      • CLUSTER_NAME: um nome para o cluster.
      • CONTROL_PLANE_LOCATION: o local do plano de controle do cluster, como us-central1.

    • Atualizar um cluster:

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

      Substitua:

      • CLUSTER_NAME: o nome do cluster.
      • CONTROL_PLANE_LOCATION: o local do plano de controle do cluster, como us-central1.

    Depois de concluir essa etapa, o GKE vai procurar uma ComputeClass chamada default no cluster. Você não vai notar nenhuma mudança nas cargas de trabalho até configurar a ComputeClass default.

  2. Crie uma ComputeClass chamada default, como nos exemplos a seguir:

    • A ComputeClass a seguir solicita séries de máquinas específicas:

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

      Essa ComputeClass solicita nós que usam instâncias N4. Se as instâncias N4 não estiverem disponíveis, a ComputeClass solicitará instâncias N2. É possível configurar a default ComputeClass com qualquer um dos campos disponíveis em a CustomResourceDefinition da ComputeClass.

    • A ComputeClass a seguir solicita a plataforma de computação otimizada para contêineres do Autopilot:

      apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: default
spec:
  autopilot:
    enabled: true
  priorities:
  - podFamily: general-purpose
  whenUnsatisfiable: ScaleUpAnyway

      Essa ComputeClass corresponde ao comportamento da ComputeClass integrada autopilot, com exceção do campo whenUnsatisfiable, que tem um valor de ScaleUpAnyway em vez de DoNotScaleUp. Essa modificação ajuda a evitar situações em que os pods que usam um seletor de nós para hardware específico permanecem em um estado pendente porque a ComputeClass padrão no nível do cluster foi aplicada a esses pods.

      A regra de prioridade podFamily coloca os pods na plataforma de computação otimizada para contêineres do Autopilot. Essa regra de prioridade exige a versão 1.35.2-gke.1485000 ou mais recente do GKE.

  3. Crie a ComputeClass default no cluster:

    kubectl apply -f PATH_TO_MANIFEST

    Substitua PATH_TO_MANIFEST pelo caminho para o manifesto da ComputeClass.

  4. Opcional: se o cluster do Standard já tiver pools de nós criados manualmente que você usa como padrão para cargas de trabalho de uso geral, é possível mover essas cargas de trabalho para serem executadas no modo Autopilot depois de definir uma ComputeClass do Autopilot como padrão no nível do cluster. Para mover essas cargas de trabalho, restrinja e drene todos os nós nos pools de nós. O GKE usa a ComputeClass padrão no nível do cluster para programar os novos pods pendentes.

Depois de definir uma ComputeClass padrão no nível do cluster, o GKE escalona pools de nós que atendem aos dois requisitos a seguir:

  • A configuração do nó é a mesma da ComputeClass default.
  • O pool de nós não tem taints ou rótulos para uma ComputeClass diferente. O GKE pode escalonar pools de nós que têm um taint e um rótulo para a ComputeClass default.

Por exemplo, se a ComputeClass default especificar a série de máquinas N4, o GKE poderá escalonar um pool de nós atual que usa instâncias N4 e não tem taints ou rótulos para uma ComputeClass diferente.

As mudanças serão aplicadas a todos os novos pods no cluster que ainda não têm uma ComputeClass. Os pods atuais poderão ser afetados dependendo das configurações de migração ativa da ComputeClass padrão no nível do cluster. Para mais informações, consulte Migração ativa em ComputeClasses padrão.

Verificar o comportamento da ComputeClass padrão

Para verificar se a ComputeClass padrão definida para um namespace ou para um cluster funciona conforme o esperado, faça o seguinte:

  1. Analise o exemplo de implantação a seguir:

    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

    Essa implantação não solicita explicitamente uma ComputeClass.

  2. Crie a implantaçã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 um dos seguintes, dependendo do que você quer verificar:

    • O nome de um namespace que tem uma ComputeClass padrão.
    • O nome de um namespace que não tem uma ComputeClass padrão.

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

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

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

    O resultado será assim:

    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. Acesse os rótulos do nó:

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

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

    O resultado será assim:

    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:

Desativar a ComputeClass padrão

Para desativar a ComputeClass padrão em um namespace ou cluster, faça uma das seguintes ações:

  • Para desativar a ComputeClass padrão no nível do namespace para todos os pods, remova o rótulo cloud.google.com/default-compute-class do namespace:

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

    O caractere - no final da chave do rótulo remove todos os rótulos com essa chave do objeto Namespace na API Kubernetes.

  • Para desativar a ComputeClass padrão no nível do namespace para pods que não sejam do DaemonSet, remova o rótulo cloud.google.com/default-compute-class-non-daemonset do namespace:

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

  • Para desativar a ComputeClass padrão no 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

A seguir