Aplicar ComputeClasses aos pods por padrão

Autopilot Standard

Neste documento, mostramos como aplicar ComputeClasses por padrão aos pods do Google Kubernetes Engine (GKE) que não selecionam explicitamente uma ComputeClass. Nesta página, há instruções para definir uma ComputeClass como padrão em um namespace e em um cluster inteiro. Este documento é destinado a administradores de cluster que querem reduzir a sobrecarga manual causada pela configuração individual de carga de trabalho e de 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 no cluster ou namespace que não selecionar uma ComputeClass diferente. Quando você implanta um pod que não seleciona uma ComputeClass, o GKE aplica ComputeClasses padrão na seguinte ordem:

1. Se o namespace tiver uma ComputeClass padrão, o GKE vai 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 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 sua ComputeClass tenha a migração ativa habilitada.

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 nas 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 CLI do Google Cloud para essa tarefa, instale e inicialize a gcloud CLI. Se você instalou a gcloud CLI anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da gcloud CLI não sejam compatíveis com a execução dos comandos neste documento.
  Observação: em instalações prévias da gcloud CLI, defina a propriedade compute/region. Se você usa principalmente clusters zonais, defina compute/zone. Ao definir um local padrão, é possível evitar erros na gcloud CLI como: One of [--zone, --region] must be supplied: Please specify location. Talvez seja necessário especificar o local em determinados comandos se o local do cluster for diferente do padrão definido.

• Ter um cluster do GKE Autopilot ou Standard que execute uma versão compatível com a definição de uma ComputeClass padrão no nível do cluster ou do namespace. Para mais informações, consulte a seção Requisitos.

• Se você estiver usando um cluster no modo Standard, verifique se atende a um dos seguintes requisitos:

  • Ative o escalonamento automático em pelo menos um pool de nós no cluster.
  • Se o cluster Standard executar uma versão anterior a 1.33.3-gke.1136000 e não estiver registrado no canal de lançamento rápido, ative o provisionamento automático de nós no nível do cluster.

• Se quiser definir uma ComputeClass personalizada como padrão para um namespace, implante uma ComputeClass personalizada.

Requisitos

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

Papéis e permissões necessárias

Para receber as permissões necessárias a fim de 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 projeto Google Cloud :

• Desenvolvedor do Kubernetes Engine (roles/container.developer)
• Atualize a ComputeClass padrão no nível do cluster: Administrador de cluster do Kubernetes Engine (roles/container.clusterAdmin)

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 necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões 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
• Adicione rótulos aos namespaces: container.namespaces.update
• Ative a ComputeClass padrão no nível do cluster: container.clusters.update

Essas permissões também podem ser concedidas com funções personalizadas 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 para usar como padrão. Se um pod implantado nesse namespace ainda não tiver selecionado uma ComputeClass, o GKE vai 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 são 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 são 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 são aplicadas a todos os novos pods nesse namespace. Os pods atuais não são afetados.

Atualizar a ComputeClass padrão em um namespace

Para substituir a ComputeClass padrão 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 são 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 essenciais. No entanto, é possível especificar uma ComputeClass padrão para pods que não são DaemonSet em namespaces do sistema, para que esses pods sejam executados separadamente das suas 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. Com esse script, é possível aplicar uma ComputeClass recomendada ou sua própria ComputeClass 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 não DaemonSet em namespaces do sistema.

   Aviso: não defina o rótulo cloud.google.com/default-compute-class para um namespace do sistema. Esse rótulo afeta os DaemonSets e pode causar interrupções no cluster.

2. Execute o script:

   ./apply-system-cc.sh
   

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

Para remover a ComputeClass padrão dos 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 classe de computação padrão para um cluster

Esta seção mostra como definir uma ComputeClass como padrão para seu cluster. Para ComputeClasses padrão no nível do cluster, não especifique manualmente taints e rótulos de nós para pools de nós atuais no cluster. O GKE não escalona pools de nós com taints de nós para ComputeClasses. Se você adicionar manualmente um rótulo para a default ComputeClass, o GKE poderá escalonar esse pool de nós. No entanto, essa configuração manual não é necessária para usar uma classe de computação padrão no nível do cluster.

Observação :em clusters do Autopilot, definir uma ComputeClass padrão para o cluster substitui o comportamento padrão do Autopilot, que coloca pods na plataforma de computação otimizada para contêineres.

1. Para ativar a definição de uma ComputeClass padrão no nível do 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:

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

   Também é possível especificar essa flag ao criar um cluster do Autopilot ou Standard.

2. Salve o manifesto a seguir, que define um ComputeClass chamado 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 solicita nós que usam instâncias N4. Se as instâncias N4 não estiverem disponíveis, a ComputeClass vai solicitar instâncias N2. É possível configurar a default ComputeClass com qualquer um dos campos disponíveis na CustomResourceDefinition da ComputeClass.

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 padrão no nível do cluster, o GKE dimensiona os pools de nós que atendem aos dois requisitos a seguir:

• A configuração do nó é a mesma da default ComputeClass.
• 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 se aplicam a todos os novos pods no cluster que ainda não têm uma ComputeClass. Os pods atuais podem ser afetados dependendo das configurações de migração ativas da ComputeClass padrão no nível do cluster. Para mais informações, consulte Migração ativa nas ComputeClasses padrão.

Verificar o comportamento padrão da ComputeClass

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 uma das seguintes opções, 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 da implantação de exemplo:

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

   O resultado será o 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. 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ó da saída da etapa anterior.

   O resultado será o 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 padrão no nível do cluster: default para nós criados pelo GKE Autopilot ou pela criação automática de pool de nós. Os nós em pools de nós criados manualmente podem não ter o rótulo cloud.google.com/compute-class.
   • ComputeClass padrão no nível do namespace: o nome da ComputeClass que você configurou como padrão do namespace.

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 de 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 são 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

• Saiba mais sobre as ComputeClasses personalizadas no GKE.