Usar o particionamento dinâmico com um programador personalizado

Neste documento, descrevemos como usar o segmentação dinâmica interagindo diretamente com Recursos personalizados de segmentação. É possível criar intervalos, monitorar estados de partição e verificar a integridade do intervalo.

Antes de seguir estas instruções, entenda os conceitos de segmentação dinâmica.

Por que usar o corte dinâmico com um programador personalizado?

Use seu próprio programador para gerenciar recursos personalizados Slice se tiver requisitos de programação complexos ou se quiser integrar o particionamento dinâmico à sua infraestrutura de programação atual.

Se você preferir usar um programador em vez de gerenciar recursos personalizados Slice diretamente, o GKE oferece integração com o Kueue e o agendamento com reconhecimento de topologia (TAS, na sigla em inglês). Para mais informações, consulte Programar intervalos dinâmicos com o Kueue e o TAS.

Visão geral do fluxo de trabalho

Para usar o corte dinâmico com um programador personalizado, faça as seguintes tarefas neste documento:

  1. Ative o controlador de fração.
  2. Criar pools de nós com provisionamento incremental.
  3. Crie recursos personalizados de fração com base nos requisitos da sua carga de trabalho. Aplique o recurso personalizado Slice ao cluster.
  4. Monitore os estados da partição e a integridade da fração.
  5. Exclua o segmento quando terminar.

Para mais informações sobre os campos e o status do recurso personalizado "Slice", consulte as informações de referência do recurso personalizado "Slice".

Requisitos

Para usar o particionamento dinâmico no GKE, você precisa atender aos seguintes requisitos:

  • Use um cluster padrão no canal rápido em uma das seguintes versões:
    • Para configuração dinâmica de supersegmentação (topologias iguais ou maiores que 4x4x4), use a versão 1.35.2-gke.1842000 ou mais recente.
    • Para configuração dinâmica de subsegmentação (topologias menores que 4x4x4), use a versão 1.36.0-gke.3712000 ou mais recente.
  • Use a versão Ironwood (TPU7x).
  • Use a imagem do Container-Optimized OS para seus nós.
  • Para usar o provisionamento incremental, use reservas no modo de capacidade total. O modo "Toda a capacidade" é um recurso ativado pelo TPU Cluster Director.
  • Para o subdimensionamento dinâmico, verifique se os nós têm eventos de manutenção pendentes. Monitore suas instâncias para eventos de manutenção pendentes. Se algum dos seus nós tiver um evento de manutenção pendente com um horário de término entre 18 de setembro de 2026 e 30 de setembro de 2026, você precisará acionar manualmente o evento de manutenção do host nesses nós antes de usar a subsegmentação.

Antes de começar

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

  • Ative 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.

Ativar o controlador de fração

Para usar o particionamento dinâmico, ative o controlador de fração no cluster.

  1. Atualize o cluster:

    gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --enable-slice-controller

    Substitua:

  2. Receba as credenciais para se comunicar com o cluster usando comandos kubectl:

    gcloud config set container/cluster CLUSTER_NAME
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=LOCATION

  3. Na saída do comando a seguir, verifique se o valor slices.accelerator.gke.io está presente:

    kubectl get crd slices.accelerator.gke.io

    O resultado será o seguinte:

    slices.accelerator.gke.io                2026-01-09T23:58:02Z

Criar pools de nós com provisionamento incremental

Nesta seção, descrevemos como criar pools de nós de TPU com provisionamento incremental. O GKE converte toda a capacidade de TPU em pools de nós de um grupo de 16 nós de VMs de TPU ou subblocos. O GKE provisiona esses pools de nós mesmo quando não consegue encontrar todas as 16 VMs íntegras, colocando nós em partes íntegras da máquina host e provisionando incrementalmente máquinas não íntegras enquanto elas são reparadas.

É possível segmentar seu pool de nós para que ele pertença a qualquer um dos seguintes itens:

  • Um bloco específico de TPUs, que é exposto em reservas no modo "Toda a capacidade". O bloqueio de segmentação permite que o GKE crie o pool de nós em qualquer sub-bloco disponível dentro do bloco especificado.
  • Um sub-bloco específico ou um grupo específico de 16 nós de VMs de TPU para um controle mais granular.

Criar uma política de carga de trabalho

Para criar um pool de nós de fração de TPU com Ironwood (TPU7x), primeiro crie uma política de carga de trabalho com o campo accelerator-topology-mode definido como provision_only. Essa configuração aciona o processo de provisionamento incremental.

Crie uma política de carga de trabalho:

gcloud compute resource-policies create workload-policy WORKLOAD_POLICY_NAME \
        --project=PROJECT_ID \
        --region=REGION  \
        --type=HIGH_THROUGHPUT \
        --accelerator-topology=4x4x4 \
        --accelerator-topology-mode=provision_only

Substitua:

  • WORKLOAD_POLICY_NAME: um nome para a política de carga de trabalho.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • REGION: a região da política de carga de trabalho.

Nesse comando, faça o seguinte:

  • Sempre defina o campo accelerator-topology como 4x4x4 para corresponder ao número total de chips em um único subbloco.
  • Sempre defina o campo accelerator-topology-mode como provision_only para garantir que o processo de provisionamento incremental seja acionado. Quando o campo provision_only é definido, o pool de nós provisiona nós de TPU sem formar links do ICI ou do OCS.

Faça com que seu pool de nós pertença a um bloco ou sub-bloco

É possível segmentar sub-blocos ou blocos específicos na sua reserva do modo "Toda a capacidade".

  • Segmentar um bloco:cada pool de nós usa a capacidade de um bloco especificado. O GKE coloca o pool de nós em um subbloco disponível nesse bloco. Você precisa criar tantos pools de nós quanto sub-blocos no bloco que quer usar.

  • Segmentar um subbloco:cada pool de nós é mapeado para um subbloco específico e disponível. Ao usar o direcionamento por sub-bloco, o GKE cria o pool de nós se pelo menos uma VM estiver íntegra. O provisionamento incremental ajuda a garantir que todos os nós sejam colocados no sub-bloco especificado.

Bloquear

  1. Para recuperar o nome do bloco em uma reserva e a contagem de sub-blocos disponíveis no bloco, siga estas etapas no documento Ver a topologia e o status de integridade de todas as reservas do modo de capacidade:

    1. Identifique o nome do bloco listando todos os blocos de reserva e copiando o valor no campo name:. Esse valor é o nome do bloco ou BLOCK_NAME neste documento.

    2. Determine quantos pools de nós criar descrevendo um bloco de reserva e identificando o valor no campo reservationSubBlockCount. Esse valor é o número de sub-blocos disponíveis. Por exemplo, o valor reservationSubBlockCount: 4 indica que o bloco tem quatro sub-blocos disponíveis, e você precisa criar quatro pools de nós separados.

  2. Defina o caminho da reserva:

    export RESERVATION_PATH="projects/PROJECT_ID/reservations/RESERVATION_NAME/reservationBlocks/BLOCK_NAME"

    Substitua:

    • RESERVATION_NAME: o nome da sua reserva de TPU.
    • BLOCK_NAME: o nome do bloco.

  3. Crie um pool de nós para cada sub-bloco identificado na etapa anterior. Por exemplo, se a contagem for 4, execute este comando quatro vezes. Use um nome exclusivo para cada pool de nós.

    gcloud container node-pools create NODE_POOL_NAME \
      --cluster=CLUSTER_NAME \
      --node-locations=ZONE \
      --machine-type=tpu7x-standard-4t \
      --num-nodes=16 \
      --placement-policy=WORKLOAD_POLICY_NAME \
      --reservation-affinity=specific \
      --reservation=${RESERVATION_PATH}

    Substitua:

    • NODE_POOL_NAME: o nome do novo pool de nós.
    • CLUSTER_NAME: o nome do cluster do GKE.
    • WORKLOAD_POLICY_NAME: o nome da política de carga de trabalho que você criou.
    • ZONE: a zona do pool de nós, por exemplo, us-central1-a.

Sub-bloco

  1. Para recuperar o nome do bloco e os IDs dos sub-blocos disponíveis, siga estas etapas no documento Ver a topologia e o status de integridade de todas as reservas do modo de capacidade:

    1. Para identificar o nome do bloco, liste todos os blocos de reserva e copie o valor no campo name:. Esse valor é o nome do bloco ou BLOCK_NAME no documento.

    2. Para identificar o nome dos sub-blocos, liste todos os sub-blocos de um bloco e copie o valor no campo name: para cada entrada em reservationSubBlocks. Esse valor é o nome do subbloco ou SUBBLOCK_NAME neste documento.

  2. Defina o caminho da reserva:

    export RESERVATION_PATH="projects/PROJECT_ID/reservations/RESERVATION_NAME/reservationBlocks/BLOCK_NAME/reservationSubBlocks/SUBBLOCK_NAME"

    Substitua:

    • RESERVATION_NAME: o nome da sua reserva de TPU.
    • BLOCK_NAME: o nome do bloco.
    • SUBBLOCK_NAME: o nome do sub-bloco.

  3. Crie o pool de nós:

    gcloud container node-pools create NODE_POOL_NAME \
        --project=PROJECT_ID \
        --cluster=CLUSTER_NAME \
        --node-locations=ZONE \
        --machine-type=tpu7x-standard-4t \
        --num-nodes=16 \
        --placement-policy=WORKLOAD_POLICY_NAME \
        --reservation-affinity=specific \
        --reservation=${RESERVATION_PATH}

    Substitua:

    • NODE_POOL_NAME: um nome exclusivo para o novo pool de nós, por exemplo, sub-block-pool-1.
    • PROJECT_ID: o ID do projeto Google Cloud .
    • CLUSTER_NAME: o nome do cluster do GKE.
    • ZONE: a zona do pool de nós, por exemplo, us-central2-b.
    • WORKLOAD_POLICY_NAME: o nome da política de carga de trabalho que você criou.

Nessa etapa, os nós são criados, mas os links Inter-Chip Interconnect (ICI) ainda não estão ativos. Portanto, não é possível executar cargas de trabalho diretamente nesses pools de nós.

Para ativar todos os links do ICI necessários para formar a fração e permitir que as cargas de trabalho sejam programadas, crie uma fração dinâmica usando um dos seguintes métodos:

  • Crie um recurso personalizado de fração. Em vez de pods, use um recurso personalizado de Slice para definir a topologia especificada, que o controlador de fração ativa.
  • Agende cargas de trabalho do GKE com o Kueue e o TAS. O Kueue processa automaticamente a criação e exclusão de recursos personalizados Slice. Evite modificar manualmente os recursos personalizados Slice criados pelo Kueue.

Formar uma segmentação dinâmica com supersegmentação ou subsegmentação

Depois de criar os pools de nós, é possível formar uma super-fatia dinâmica maior ou uma subfatia dinâmica menor criando um recurso personalizado do tipo "Slice". Um recurso personalizado de Slice define a topologia especificada, que o controlador de fração ativa. Em seguida, as cargas de trabalho são programadas e executadas nessa fração dinâmica.

Partições de intervalos dinâmicos

As partições fornecem as topologias disponíveis para formar uma fração dinâmica das suas cargas de trabalho. Uma partição mostra todas as topologias disponíveis para cada nó, incluindo 2x2x1, 2x2x2, 2x2x4, 2x4x4 e 4x4x4. Topologias menores que 4x4x4 exigem a versão 1.36.0-gke.3712000 ou mais recente do GKE.

As fatias maiores que 4x4x4 não têm um rótulo de partição, porque são criadas associando várias partições 4x4x4.

Cada nó da TPU em um pool de nós de provisionamento incremental precisa ter todos os ID de partição e rótulos de nó de estado de partição especificados.

Verificar o status dos nós e das partições

  1. Para receber os nomes dos nós do pool de nós, execute o comando a seguir:

    kubectl get nodes -l cloud.google.com/gke-nodepool=${NODE_POOL_NAME}

    O resultado será assim:

    NAME                                 STATUS   ROLES    AGE    VERSION
gke-np-status-update-7b4c890c-0jhp   Ready    <none>   2d1h   v1.35.1-gke.1396002
gke-np-status-update-7b4c890c-377r   Ready    <none>   2d1h   v1.35.1-gke.1396002
gke-np-status-update-7b4c890c-gb51   Ready    <none>   2d1h   v1.35.1-gke.1396002

  2. Verifique o modelo de provisionamento do nó:

    kubectl describe node NODE_NAME | grep "cloud.google.com/gke-accelerator-topology-mode"

    O resultado será assim:

    cloud.google.com/gke-accelerator-topology-mode: PROVISION_ONLY

  3. Recupere as informações do rótulo do nó para a partição de topologia que você quer segmentar:

    kubectl describe node NODE_NAME | grep -E "cloud.google.com/gke-tpu-partition-.*-id"

    Substitua NODE_NAME pelo nome de um dos nós no pool de nós.

    O resultado será assim:

    cloud.google.com/gke-tpu-partition-4x4x4-id=fba785f80d18552357dcdef6d3d16c27
cloud.google.com/gke-tpu-partition-2x4x4-id=e18372d627ac412cb24d5ea8ab8912c9
cloud.google.com/gke-tpu-partition-2x2x4-id=7fbd4e29dc1839217fae41a9dd8211b4
cloud.google.com/gke-tpu-partition-2x2x2-id=a9476d1b02bd4f4e75ffffae3bd23c01
cloud.google.com/gke-tpu-partition-2x2x1-id=0bcfe937d1bb3914a8bdcd94e9f73319

  4. Verifique se o nó inclui a anotação node.gke.io/created-by-mig:

    kubectl describe node NODE_NAME | grep "node.gke.io/created-by-mig"

    Substitua NODE_NAME pelo nome de um dos nós no pool de nós.

    O resultado será assim:

    node.gke.io/created-by-mig: projects/735972712744/zones/us-central1-ai1a/team/string

    A saída inclui a anotação node.gke.io/created-by-mig, que permite que o plano de controle do GKE vincule nós do Kubernetes aos recursos do Compute Engine subjacentes.

  5. Recupere as informações do rótulo do nó para o estado da partição de topologia que você quer verificar:

    kubectl describe node NODE_NAME | grep -E "cloud.google.com/gke-tpu-partition-.*-state"

    O resultado será assim:

    cloud.google.com/gke-tpu-partition-4x4x4-state=HEALTHY
cloud.google.com/gke-tpu-partition-2x4x4-state=HEALTHY
cloud.google.com/gke-tpu-partition-2x2x4-state=HEALTHY
cloud.google.com/gke-tpu-partition-2x2x2-state=HEALTHY
cloud.google.com/gke-tpu-partition-2x2x1-state=HEALTHY

    O rótulo cloud.google.com/gke-tpu-partition-[shape]-state (em que [shape] corresponde à topologia do ID da partição) indica se a partição está disponível para formar uma fração dinâmica. Esse rótulo de estado aceita os seguintes valores:

    • HEALTHY: a partição está íntegra e totalmente funcional.
    • DEGRADED: a partição está prejudicada, mas ainda pode ser usada para a formação de intervalos dinâmicos. Esse estado se aplica apenas à topologia 4x4x4 de nível superior. Topologias menores não têm um estado degradado.
    • UNHEALTHY: a partição está com mau funcionamento e não pode ser usada para formar uma fatia.
    • UNSET: o estado não está definido devido à inicialização sem êxito do controlador de fração do GKE.
    • INCOMPLETE: nem todos os nós na partição são provisionados.

Criar um recurso personalizado de fração

O recurso personalizado de fração varia um pouco dependendo se você está criando uma superfração dinâmica ou uma subfração dinâmica.

  1. Defina o recurso personalizado Slice:

    apiVersion: accelerator.gke.io/v1beta1
kind: Slice
metadata:
  # Name of the slice resource
  name: SLICE_NAME
spec:
  # Specify the type of accelerator for this slice
  type: "tpu7x"
  # Define the desired topology for the accelerator slice
  topology: TOPOLOGY
  partitionIds:
    - PARTITION_ID # Example: a9476d1b02bd4f4e75ffffae3bd23c01
    - PARTITION_ID_2
    # ... add more partition IDs as needed

    Substitua:

    • SLICE_NAME: um nome para a fração. O nome precisa atender às condições de metadata.name e ter até 49 caracteres.
    • TOPOLOGY: a topologia da fração dinâmica. A topologia precisa atender às seguintes condições:
      • Para subsegmentação dinâmica:é possível especificar topologias menores que 4x4x4, como 2x2x1, 2x2x2, 2x2x4 ou 2x4x4. Essas topologias menores exigem o GKE versão 1.36.0-gke.3712000 ou posterior.
      • Para supersegmentação dinâmica:é possível especificar topologias iguais ou maiores que 4x4x4. Para configurar o supersegmento dinâmico, cada dimensão da topologia solicitada precisa ser um múltiplo de quatro, por exemplo, 4A x 4B x 4C. Os três valores nas dimensões da topologia, AxBxC, precisam estar em ordem não decrescente (A ≤ B ≤ C). Por exemplo, 4x4x8 é válido, mas 4x8x4 não é. Essa ordem ajuda a garantir a formação consistente de intervalos e evita comportamentos inesperados. O produto dos três valores nas dimensões de topologia, A × B × C,não pode exceder 9.216.
    • PARTITION_ID: uma lista de strings que identificam as partições que compõem a fração.
      • Para subdivisão dinâmica:especifique exatamente um ID de partição.
      • Para supersegmentação dinâmica:calcule o número de partições com base no número total de chips, em que cada partição consiste em 64 chips. O número de itens na sua lista spec.partitionIds precisa corresponder exatamente ao número calculado de partições ((A × B × C) / 64).
      • A lista partitionIds precisa atender às seguintes condições:
        • Cada partição precisa ser mapeada para um subbloco de reserva.
        • Todos os sub-blocos associados precisam pertencer à mesma reserva.
        • Todos os sub-blocos associados precisam estar na mesma reserva.
        • Os pools de nós associados precisam ter todos os nós no estado ready.
    • O valor do campo type precisa ser tpu7x.
    • Se quiser permitir que o controlador de fração tente de novo automaticamente durante a formação de fração, adicione a anotação slice.gke.io/retry-on-failure: "true" ao recurso personalizado de fração. Se a fração não for criada devido ao motivo do status SliceCreationFailed, o controlador vai tentar de novo até que a fração seja formada.

    Por exemplo, para criar uma fração de 4x8x8 (supersegmentação dinâmica), você precisa fornecer quatro IDs de partição exclusivos.

    apiVersion: accelerator.gke.io/v1beta1
kind: Slice
metadata:
    name: test-super-slice-example
    annotations:
      slice.gke.io/retry-on-failure: "true"
spec:
    type: "tpu7x"
    topology: "4x8x8" # (4*8*8)/64 = 4 partitions
    partitionIds:
        - "p0-4x4x4"
        - "p1-4x4x4"
        - "p2-4x4x4"
        - "p3-4x4x4"

    Por exemplo, para criar uma fração 2x2x2 (subdivisão dinâmica), é necessário fornecer um ID de partição exclusivo.

    apiVersion: accelerator.gke.io/v1beta1
kind: Slice
metadata:
  name: test-sub-slice-example
  annotations:
      slice.gke.io/retry-on-failure: "true"
spec:
  type: "tpu7x"
  topology: "2x2x2"
  partitionIds:
    - "fba785f80d18552357dcdef6d3d16c27" # Only 1 partitionId for sub-slice

  2. Aplique o recurso personalizado "Slice":

    kubectl apply -f test-slice-example.yaml

    Nesse ponto, o GKE tenta criar a fração. Se um dos problemas a seguir ocorrer, a criação de intervalos vai falhar, e o motivo do status no recurso personalizado Slice será atualizado para SliceCreationFailed ou FAILED:

    • Se os nós selecionados no recurso personalizado não existirem, o motivo do status será SliceCreationFailed.
    • Se algum nó no recurso personalizado for usado por outra fração, o motivo do status será SliceCreationFailed.
    • Se os nós no recurso personalizado não fizerem parte do mesmo subbloco de reserva, o motivo do status será FAILED.
    • Se os nós não estiverem na mesma reserva, o motivo do status será FAILED.
    • Se a topologia não corresponder ao número de partições, o motivo do status será SliceCreationFailed.

    Para tentar novamente a formação de intervalos automaticamente quando o status for SliceCreationFailed, configure a anotação slice.gke.io/retry-on-failure: "true" conforme descrito em Criar um recurso Slice intervalo.

    Para saber mais sobre o status do recurso personalizado "Slice", consulte Status da fatia.

Monitorar o status do recurso personalizado Slice

Para verificar o status do recurso personalizado Slice, execute o seguinte comando:

kubectl describe slice SLICE_NAME

Substitua SLICE_NAME pelo nome da fração.

O resultado será o seguinte:

Name:         test-slice
Namespace:
Labels:       <none>
Annotations:  <none>
API Version:  accelerator.gke.io/v1beta1
Kind:         Slice
Metadata:
  Creation Timestamp:  2026-01-11T23:45:15Z
  Finalizers:
    accelerator.gke.io/slice-finalizer
  Generation:        1
  Resource Version:  1768175347356335006
  UID:               d0b71e5c-be3f-4788-aead-930c7afec4f2
Spec:
  Partition Ids:
    2c79463990ff67c4e3c2648666bfedfa
    ba898ffcac0ad0946e8ff036d771ee53
    [more partition IDs]
  Topology:  8x16x16
  Type:      tpu7x
Status:
  Conditions:
    Last Transition Time:  2026-01-11T23:45:38Z
    Message:               ""
    
    Reason:                FAILED
    
    Status:                False
    Type:                  Ready
Events:

O campo reason no status do recurso personalizado Slice indica o estado atual do ciclo de vida. Os estados possíveis variam dependendo do uso de subsegmentação ou supersegmentação dinâmica.

Condições de status para segmentação secundária dinâmica

  • SliceNotCreated: o controlador realiza a inicialização e as verificações de recursos.
    • Se os pré-requisitos não forem atendidos, o estado vai mudar para SliceCreationFailed.
    • Se a validação for aprovada, o estado vai mudar para ACTIVATING.
  • ACTIVATING: o GKE está formando a fração.
    • Se for bem-sucedido, o estado vai mudar para ACTIVE.
    • Se os sub-blocos estiverem degradados, mas o segmento for utilizável, o estado vai mudar para ACTIVE_DEGRADED.
    • Se a formação falhar, o estado vai mudar para FAILED.
  • DEACTIVATING: se o recurso personalizado de Slice for excluído ou ocorrer uma falha crítica em um estado ativo ou com falha, a fração começará a ser desmontada.
  • INCOMPLETE: a etapa final antes da exclusão completa do recurso.

Condições de status para a supersegmentação dinâmica

  • SliceNotCreated: a fração ainda não foi criada. O controlador de fração está sendo inicializado e realizando verificações de simulação para a formação de frações.
  • SliceCreationFailed: a criação falhou porque os pré-requisitos não foram atendidos (por exemplo, os recursos necessários do Compute Engine estão faltando) ou as verificações de pré-voo falharam. Para tentar novamente a formação de intervalos automaticamente nesse estado, configure a anotação slice.gke.io/retry-on-failure: "true".
  • ACTIVATING: a fração está em processo de formação (junção).
  • ACTIVE: o slice está totalmente formado, íntegro e pronto para executar cargas de trabalho.
  • ACTIVE_DEGRADED: a fração é formada, mas inclui cubos degradados, com suporte da capacidade de recuperação de ICI. As cargas de trabalho podem ser executadas, mas o desempenho pode ser afetado. A supersegmentação dinâmica é resiliente a falhas em um único switch de circuito óptico (OCS). Se uma única unidade do OCS falhar, todos os links ópticos que atravessam esse switch ficarão indisponíveis, o que fará com que todos os cubos no superpod operem em um estado degradado.
  • DEACTIVATING: a fração está em processo de desativação.
  • FAILED: a fração não está mais pronta para executar cargas de trabalho. Esse estado ocorre se a formação inicial falhar ou se uma fração ativa tiver uma falha crítica de software ou hardware.
  • INCOMPLETE: não há cubos disponíveis suficientes para iniciar a formação de supersegmentos.

Para saber mais sobre o status do recurso personalizado "Slice", consulte Status da fração.

Executar cargas de trabalho na divisão dinâmica

Quando o recurso personalizado de fração está no estado ACTIVE, é possível executar cargas de trabalho nele. A seção a seguir inclui exemplos de cargas de trabalho que usam o segmentação dinâmica. As cargas de trabalho são enviadas como jobs ou JobSets.

Exemplo 1: uma única carga de trabalho usa uma única fração

O exemplo a seguir mostra uma carga de trabalho que usa uma única supersegmentação dinâmica 4x4x4.

  1. Salve o seguinte manifesto de amostra como tpu-job-jax-v7x-64.yaml:

    # Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

apiVersion: v1
kind: Service
metadata:
  name: headless-svc
spec:
  clusterIP: None
  selector:
    job-name: tpu-job-jax-v7x-64
---
apiVersion: batch/v1
kind: Job
metadata:
  name: tpu-job-jax-v7x-64
spec:
  backoffLimit: 0
  completions: 16
  parallelism: 16
  completionMode: Indexed
  template:
    metadata:
      annotations:
        cloud.google.com/gke-tpu-slice-topology: 4x4x4
    spec:
      nodeSelector:
        cloud.google.com/gke-tpu-topology: 4x4x4
        cloud.google.com/gke-tpu-accelerator: tpu7x
        cloud.google.com/gke-tpu-slice: test-slice
      subdomain: headless-svc
      restartPolicy: Never
      containers:
      - name: tpu-job-jax
        env:
        - name: TPU_ACCELERATOR_TYPE
          value: tpu7x-128
        image: python:3.12
        securityContext:
          privileged: false
        command:
        - bash
        - -c
        - |
          set -ex
          pip install -U --pre jax jaxlib libtpu requests -i https://us-python.pkg.dev/ml-oss-artifacts-published/jax/simple/ -f https://storage.googleapis.com/jax-releases/libtpu_releases.html
          pip list
          python -c 'import jax; print("Total TPU devices (cores):", jax.device_count())'
        resources:
          requests:
            google.com/tpu: 4
          limits:
            google.com/tpu: 4

    Nesse manifesto:

    • cloud.google.com/gke-tpu-slice-topology e cloud.google.com/gke-tpu-topology definem a topologia da fração dinâmica.
    • env.value: tpu7x-128 é o tipo de acelerador de TPU e o número total de núcleos na fração. O número de núcleos é calculado multiplicando as dimensões da topologia pelo número de núcleos por chip. Por exemplo, para uma topologia 4x4x4, o cálculo é 4 × 4 × 4 × 2 = 128, em que 2 é o número de núcleos por chip para tpu7x (Ironwood (TPU7x)). Portanto, o TPU_ACCELERATOR_TYPE é tpu7x-128.

  2. Aplique o manifesto tpu-job-jax-v7x-64.yaml:

    kubectl apply -f tpu-job-jax-v7x-64.yaml

Exemplo 2: implante uma carga de trabalho em pools de nós multislice usando JobSet

Este exemplo demonstra como implantar uma carga de trabalho em pools de nós multislice usando o JobSet.

  1. Instale o JobSet:

    kubectl apply --server-side -f https://github.com/kubernetes-sigs/jobset/releases/download/JOBSET_VERSION/manifests.yaml

    Substitua JOBSET_VERSION pela versão necessária do JobSet. Para subsegmentação dinâmica, use o JobSet v0.12.0 ou mais recente. Para o supersegmento dinâmico, use o JobSet v0.11.1 ou mais recente.

  2. Salve o seguinte manifesto de amostra como tpu-multislice-jax.yaml:

    # Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

apiVersion: jobset.x-k8s.io/v1alpha2
kind: JobSet
metadata:
  name: tpu-multislice-jax
  annotations:
    alpha.jobset.sigs.k8s.io/exclusive-topology: cloud.google.com/gke-tpu-slice
spec:
  failurePolicy:
    maxRestarts: 3
  replicatedJobs:
  - name: slice-job
    replicas: 2
    template:
      spec:
        parallelism: 16
        completions: 16
        backoffLimit: 0
        completionMode: Indexed
        template:
          metadata:
            annotations:
              # The shape of the slice
              cloud.google.com/gke-tpu-slice-topology: 4x4x4
          spec:
            hostNetwork: true
            dnsPolicy: ClusterFirstWithHostNet
            nodeSelector:
              cloud.google.com/gke-tpu-topology: 4x4x4
              cloud.google.com/gke-tpu-accelerator: tpu7x
              # IMPORTANT: Do NOT put 'cloud.google.com/gke-tpu-slice' here manually.
              # The exclusive-topology annotation handles the slice assignment automatically.
            containers:
            - name: jax-worker
              image: python:3.12
              securityContext:
                privileged: true
              ports:
              - containerPort: 8471
              command:
              - bash
              - -c
              - |
                set -ex
                pip install -U --pre jax jaxlib libtpu requests -f https://storage.googleapis.com/jax-releases/libtpu_releases.html
                # Verify JobSet injected the specific slice ID for this worker
                echo "JobSet Index: $JOB_COMPLETION_INDEX"
                python -c 'import jax; print("Total TPU devices:", jax.device_count())'
              resources:
                requests:
                  google.com/tpu: 4
                limits:
                  google.com/tpu: 4

  3. Aplique o manifesto tpu-multislice-jax.yaml:

    kubectl apply -f tpu-multislice-jax.yaml

    Nesse manifesto:

    • O campo replicas: 2 em replicatedJobs indica que o JobSet cria dois jobs separados, cada um correspondente a uma fração de TPU 4x4x4.
    • A anotação alpha.jobset.sigs.k8s.io/exclusive-topology: cloud.google.com/gke-tpu-slice ajuda a garantir que cada job seja atribuído a uma fração de TPU exclusiva.
    • A anotação cloud.google.com/gke-tpu-slice-topology: 4x4x4 define a topologia de cada fração dinâmica.
    • A variável de ambiente TPU_ACCELERATOR_TYPE não está definida explicitamente neste exemplo porque o JobSet processa a atribuição de fração. O código JAX detecta automaticamente os dispositivos TPU disponíveis na fração atribuída.

Excluir a fração

  1. Exclua a fração:

    kubectl patch slice $SLICE_NAME --type json \
  -p='[{"op": "remove", "path": "/metadata/finalizers"}]'

  2. Verifique se a fração foi excluída:

    kubectl get slices

Fazer upgrade dos pools de nós

Se você fizer upgrade de pools de nós configurados com provisionamento incremental, use parâmetros de sobretensão específicos para evitar conflitos de capacidade.

Para configurar e executar o upgrade do pool de nós:

  1. Se você estiver usando o super-slicing dinâmico, exclua as fatias ativas antes de executar a manutenção manual:

    kubectl delete slice SLICE_NAME

    Se você estiver usando a subdivisão dinâmica, não será necessário excluir as fatias ativas primeiro. No entanto, as subpartes que permanecerem ativas durante um upgrade vão falhar e fazer a transição para um estado FAILED.

  2. Atualize os parâmetros de upgrade do pool de nós:

    gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --max-surge-upgrade=0 \
    --max-unavailable-upgrade=16

    Verifique se o campo --max-surge-upgrade está definido como 0 para evitar que o GKE tente alocar TPUs extras durante o upgrade. Recomendamos definir o campo --max-unavailable-upgrade=16 para fazer upgrade de um subbloco completo de 16 nós simultaneamente.

  3. Faça upgrade do pool de nós:

    gcloud container clusters upgrade CLUSTER_NAME \
    --node-pool=NODE_POOL_NAME \
    --cluster-version=CLUSTER_VERSION \
    --project=PROJECT_ID \
    --location=LOCATION

Manutenção e falhas de hardware

Se você acionar uma manutenção iniciada pelo cliente ou se ocorrer um failover de hardware, apenas os nós segmentados serão afetados, e não todo o pool de nós.

Para o supersegmento dinâmico, é necessário excluir os segmentos dinâmicos ativos antes de executar a manutenção manual. Se você estiver usando a subsegmentação dinâmica, não será necessário excluir os segmentos ativos primeiro. Se ocorrerem falhas de hardware ou manutenção enquanto uma subpartição dinâmica estiver ativa, o sistema vai processar a recuperação da seguinte maneira:

  1. Remodelagem automática: o GKE remodela automaticamente a fatia dinâmica ativa quando a manutenção começa em um host associado.
  2. Falha no recurso personalizado de fração: o recurso personalizado de fração faz a transição para um estado FAILED.
  3. Observação do programador: o programador observa o estado de falha do recurso personalizado Slice.
  4. Processo de reforma: o programador tenta recriar automaticamente as configurações de fração em outros nós íntegros disponíveis.

Desativar o controlador de fração

Para desativar o controlador de fração, remova-o do cluster.

  1. Verifique se os recursos personalizados de Slice estão vazios:

    kubectl get slice -A

  2. Atualize o cluster para desativar o controlador de fração:

    gcloud container clusters update ${CLUSTER_NAME} \
    --location=${REGION} \
    --no-enable-slice-controller

  3. Exclua o recurso personalizado de fração :

    kubectl delete crd slices.accelerator.gke.io

  4. Verifique se o recurso personalizado de Slice foi excluído:

    kubectl get crd | grep slices.accelerator.gke.io

  5. Remova os rótulos adicionados pelo controlador de segmentação. Remova estes rótulos:

    • cloud.google.com/gke-tpu-slice
    • cloud.google.com/gke-tpu-topology
    1. Para remover de um nó específico, atualize o nome dele.
    export NODE_NAME="gke-tpu-bdac9600-3bdg"
kubectl label node $NODE_NAME cloud.google.com/gke-tpu-slice- cloud.google.com/gke-tpu-slice-topology-
    1. Se você quiser remover esses rótulos de todos os nós do cluster:
    kubectl label nodes --all cloud.google.com/gke-tpu-slice- cloud.google.com/gke-tpu-slice-topology-
    1. Verifique os rótulos do nó e confirme se eles estão vazios:
    export NODE_NAME="gke-tpu-bdac9600-3bdg"
kubectl describe node $NODE_NAME | grep "cloud.google.com/gke-tpu-slice"

A seguir