Programa segmentos dinámicos con Kueue y TAS

En este documento, se explica cómo aprovisionar grupos de nodo TPU y programar porciones dinámicas en Google Kubernetes Engine (GKE) con Kueue y la programación basada en la topología (TAS).

También puedes usar la segmentación dinámica interactuando directamente con los recursos personalizados de Slice. Para obtener más información, consulta Usa la segmentación dinámica con un programador personalizado.

Antes de seguir estas instrucciones, asegúrate de comprender los conceptos de la segmentación dinámica.

Requisitos

Para usar la segmentación dinámica en GKE, debes cumplir con los siguientes requisitos:

  • Usa un clúster de Standard en el canal rápido en una de las siguientes versiones:
    • Para la configuración de super-slicing dinámico (topologías iguales o superiores a 4x4x4), usa la versión 1.35.2-gke.1842000 o una posterior.
    • Para la configuración de subsegmentación dinámica (topologías más pequeñas que 4x4x4), usa la versión 1.36.0-gke.3712000 o una posterior.
  • Usa la versión Ironwood (TPU7x).
  • Usa la imagen de Container-Optimized OS para tus nodos.
  • Para usar el aprovisionamiento incremental, usa las reservas del modo All Capacity. El modo All Capacity es una función habilitada por Cluster Director de TPU.
  • Para la división dinámica en porciones secundarias, asegúrate de que tus nodos tengan eventos de mantenimiento pendientes. Supervisa tus instancias para detectar eventos de mantenimiento pendientes. Si alguno de tus nodos tiene un evento de mantenimiento pendiente con una hora de finalización entre el 18 de septiembre de 2026 y el 30 de septiembre de 2026, debes activar el evento de mantenimiento del host de forma manual en esos nodos antes de poder usar la división en porciones secundarias.

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

  • Habilita la API de Google Kubernetes Engine.
    • Habilitar la API de Google Kubernetes Engine
  • Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste gcloud CLI, ejecuta el comando gcloud components update para obtener la versión más reciente. Es posible que las versiones anteriores de gcloud CLI no admitan la ejecución de los comandos de este documento.

Usa la segmentación dinámica en GKE con Kueue

En esta sección, se describe el flujo de trabajo para usar la segmentación dinámica en GKE.

  1. Visualiza la topología y el estado de las reservas en el modo All Capacity.
  2. Habilita el controlador de porciones en tu clúster.
  3. Instala Kueue, JobSet y LWS.
  4. Crea nodo TPU TPU.
  5. Configura Kueue para crear un recurso personalizado Slice.
  6. Ejecuta cargas de trabajo en la segmentación dinámica con Kueue.
  7. Realiza una limpieza.

Habilita el controlador de porciones

Para usar la segmentación dinámica, habilita el controlador de porciones en tu clúster.

  1. Actualiza tu clúster:

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

    Reemplaza lo siguiente:

  2. Obtén credenciales para poder comunicarte con tu clúster con los comandos de kubectl:

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

  3. En el resultado del siguiente comando, verifica que el valor slices.accelerator.gke.io esté presente:

    kubectl get crd slices.accelerator.gke.io

    El resultado es similar a lo siguiente:

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

Instala Kueue, JobSet y LWS

Si ya instalaste Kueue, JobSet y LWS, puedes omitir esta sección.

Instala Kueue

Sigue las instrucciones de la documentación de Kueue o ejecuta el siguiente comando:

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

Reemplaza KUEUE_VERSION por la versión de Kueue requerida según tus requisitos de topología. Para la división dinámica en porciones, usa Kueue v0.18.2 o una versión posterior. Para la división dinámica en porciones, usa Kueue v0.16.6 o una versión posterior.

Instala JobSet

Sigue las instrucciones de la documentación de JobSet o ejecuta el siguiente comando:

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

Reemplaza JOBSET_VERSION por la versión de JobSet requerida según tus requisitos de topología. Para la división dinámica en porciones secundarias, usa JobSet v0.12.0 o una versión posterior. Para el super-slicing dinámico, usa JobSet v0.11.1 o una versión posterior.

Instala LWS

LeaderWorkerSet (LWS) solo es necesario para la división dinámica en porciones secundarias.

Sigue las instrucciones de la documentación de LWS o ejecuta el siguiente comando:

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

Reemplaza LWS_VERSION por la versión de LWS requerida. Usa LWS v0.8.0 o una versión posterior.

Crea grupos de nodos con aprovisionamiento incremental

En esta sección, se describe cómo crear los grupos de nodo TPU con aprovisionamiento incremental. GKE convierte toda tu capacidad de TPU en grupos de nodos que comprenden grupos de 16 nodos de VMs de Ironwood (TPU7x) o subbloques. GKE aprovisiona estos grupos de nodos incluso cuando no puede encontrar todas las VMs en buen estado, ya que coloca nodos en partes en buen estado de la máquina anfitrión y aprovisiona de forma incremental las máquinas en mal estado mientras se reparan.

Puedes segmentar tu grupo de nodos para que pertenezca a cualquiera de las siguientes opciones:

  • Un bloque específico de TPU, que se expone en las reservas del modo All Capacity. La segmentación por bloques permite que GKE cree el grupo de nodos en cualquier subbloque disponible dentro del bloque especificado.
  • Un subbloque específico o un grupo específico de 16 nodos de VMs de Ironwood (TPU7x) de TPU para un control más detallado.

Crear una política de cargas de trabajo

Para crear un grupo de nodos de porción de TPU con Ironwood (TPU7x), primero debes crear una política de carga de trabajo con el campo accelerator-topology-mode establecido en provision_only. Este parámetro de configuración activa el proceso de aprovisionamiento incremental.

Crea una política de cargas de trabajo:

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

Reemplaza lo siguiente:

  • WORKLOAD_POLICY_NAME: Es un nombre para tu política de carga de trabajo.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • REGION: Es la región de la política de carga de trabajo.

En este comando, haz lo siguiente:

  • Siempre configura el campo accelerator-topology como 4x4x4 para que coincida con la cantidad total de chips dentro de un solo subbloque.
  • Establece siempre el campo accelerator-topology-mode en provision_only para asegurarte de que se active el proceso de aprovisionamiento incremental. Cuando se establece el campo provision_only, el grupo de nodos aprovisiona nodos TPU sin formar vínculos de ICI ni OCS.

Orienta tu grupo de nodos para que pertenezca a un bloque o un subbloque

Puedes segmentar subbloques o bloques específicos dentro de tu reserva en el modo All Capacity.

  • Orientar a un bloque: Cada grupo de nodos usa la capacidad de un bloque especificado. GKE coloca el grupo de nodos dentro de un subbloque disponible en ese bloque. Debes crear tantos grupos de nodos como subbloques haya en el bloque que deseas usar.

  • Orientar a un subbloque: Cada grupo de nodos se asigna a un subbloque específico y disponible. Cuando se usa la segmentación por subbloque, GKE crea el grupo de nodos si al menos una VM está en buen estado. El aprovisionamiento incremental ayuda a garantizar que todos los nodos se ubiquen dentro del subbloque especificado.

Bloquear

  1. Para recuperar el nombre del bloque en una reserva y el recuento de subbloques disponibles en el bloque, completa los siguientes pasos en el documento Visualiza la topología y el estado de las reservas en el modo All Capacity:

    1. Identifica el nombre del bloque enumerando todos los bloques de reserva y copiando el valor en el campo name:. Este valor es el nombre del bloque o BLOCK_NAME en este documento.

    2. Determina cuántos grupos de nodos crear describiendo un bloque de reserva e identificando el valor en el campo reservationSubBlockCount. Este valor es la cantidad de subbloques disponibles. Por ejemplo, el valor reservationSubBlockCount: 4 indica que el bloque tiene cuatro subbloques disponibles y que debes crear cuatro grupos de nodos independientes.

  2. Establece la ruta de acceso de la reserva:

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

    Reemplaza lo siguiente:

    • RESERVATION_NAME: Es el nombre de tu reserva de TPU.
    • BLOCK_NAME: Es el nombre del bloque.

  3. Crea un grupo de nodos para cada subbloque identificado en el paso anterior. Por ejemplo, si el recuento es 4, ejecuta este comando cuatro veces. Usa un nombre único para cada grupo de nodos.

    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}

    Reemplaza lo siguiente:

    • NODE_POOL_NAME: es el nombre de tu grupo de nodos nuevo.
    • CLUSTER_NAME: Es el nombre del clúster de GKE.
    • WORKLOAD_POLICY_NAME: Es el nombre de la política de carga de trabajo que creaste.
    • ZONE: Es la zona del grupo de nodos, por ejemplo, us-central1-a.

En subbloque

  1. Para recuperar el nombre del bloque y los IDs de los subbloques disponibles, completa los siguientes pasos en el documento Visualiza la topología y el estado de las reservas en el modo All Capacity:

    1. Para identificar el nombre del bloque, enumera todos los bloques de reserva y copia el valor en el campo name:. Este valor es el nombre del bloque o BLOCK_NAME en este documento.

    2. Para identificar el nombre de los subbloques, enumera todos los subbloques de un bloque y copia el valor en el campo name: para cada entrada en reservationSubBlocks. Este valor es el nombre del subbloque o SUBBLOCK_NAME en este documento.

  2. Establece la ruta de acceso de la reserva:

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

    Reemplaza lo siguiente:

    • RESERVATION_NAME: Es el nombre de tu reserva de TPU.
    • BLOCK_NAME: Es el nombre del bloque.
    • SUBBLOCK_NAME: el nombre del subbloque.

  3. Crea el grupo de nodos:

    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}

    Reemplaza lo siguiente:

    • NODE_POOL_NAME: Es un nombre único para el grupo de nodos nuevo, por ejemplo, sub-block-pool-1.
    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • CLUSTER_NAME: el nombre del clúster de GKE.
    • ZONE: Es la zona del grupo de nodos, por ejemplo, us-central2-b.
    • WORKLOAD_POLICY_NAME: Es el nombre de la política de carga de trabajo que creaste.

En esta etapa, se crean los nodos, pero sus vínculos de interconexión entre chips (ICI) aún no están activos. Por lo tanto, no puedes ejecutar cargas de trabajo en estos grupos de nodos directamente.

Para habilitar todos los vínculos de ICI necesarios para formar el segmento y permitir que se programen las cargas de trabajo, crea un segmento dinámico con uno de los siguientes métodos:

  • Crea un recurso personalizado Slice. En lugar de Pods, usas un recurso personalizado Slice para definir la topología especificada, que activa el controlador de porciones.
  • Programa cargas de trabajo de GKE con Kueue y TAS. Kueue controla automáticamente la creación y eliminación de recursos personalizados de Slice. Evita modificar manualmente los recursos personalizados de Slice creados por Kueue.

Crea un segmento dinámico con Kueue y TAS

En esta sección, programarás cargas de trabajo de GKE con Kueue y TAS.

Instala el controlador de porciones de Kueue

  1. Para instalar el controlador de porciones de Kueue, guarda el siguiente manifiesto como slice-controller.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: Namespace
metadata:
  labels:
    app.kubernetes.io/managed-by: kustomize
    app.kubernetes.io/name: slice-controller
    control-plane: controller-manager
  name: slice-controller-system
---
apiVersion: v1
kind: ServiceAccount
metadata:
  labels:
    app.kubernetes.io/managed-by: kustomize
    app.kubernetes.io/name: slice-controller
    control-plane: controller-manager
  name: slice-controller-controller-manager
  namespace: slice-controller-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  labels:
    app.kubernetes.io/managed-by: kustomize
    app.kubernetes.io/name: slice-controller
    control-plane: controller-manager
  name: slice-controller-leader-election-role
  namespace: slice-controller-system
rules:
- apiGroups:
  - ""
  resources:
  - configmaps
  verbs:
  - get
  - list
  - watch
  - create
  - update
  - patch
  - delete
- apiGroups:
  - coordination.k8s.io
  resources:
  - leases
  verbs:
  - get
  - list
  - watch
  - create
  - update
  - patch
  - delete
- apiGroups:
  - ""
  resources:
  - events
  verbs:
  - create
  - patch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  labels:
    app.kubernetes.io/managed-by: kustomize
    app.kubernetes.io/name: slice-controller
    control-plane: controller-manager
  name: slice-controller-webhook-secrets-role
  namespace: slice-controller-system
rules:
- apiGroups:
  - ""
  resources:
  - secrets
  verbs:
  - get
  - list
  - watch
  - update
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  labels:
    control-plane: controller-manager
  name: slice-controller-manager-role
rules:
- apiGroups:
  - ""
  resources:
  - nodes
  - pods
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - accelerator.gke.io
  resources:
  - slices
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - accelerator.gke.io
  resources:
  - slices/finalizers
  verbs:
  - update
- apiGroups:
  - accelerator.gke.io
  resources:
  - slices/status
  verbs:
  - get
  - patch
  - update
- apiGroups:
  - admissionregistration.k8s.io
  resources:
  - mutatingwebhookconfigurations
  verbs:
  - get
  - list
  - update
  - watch
- apiGroups:
  - batch
  resources:
  - jobs
  verbs:
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - events.k8s.io
  resources:
  - events
  verbs:
  - create
  - patch
  - update
  - watch
- apiGroups:
  - jobset.x-k8s.io
  resources:
  - jobsets
  verbs:
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - kueue.x-k8s.io
  resources:
  - admissionchecks
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - kueue.x-k8s.io
  resources:
  - admissionchecks/status
  - workloads/status
  verbs:
  - get
  - patch
  - update
- apiGroups:
  - kueue.x-k8s.io
  resources:
  - workloads
  verbs:
  - create
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - leaderworkerset.x-k8s.io
  resources:
  - leaderworkersets
  verbs:
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - ray.io
  resources:
  - rayclusters
  - rayjobs
  verbs:
  - get
  - list
  - patch
  - update
  - watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  labels:
    control-plane: controller-manager
  name: slice-controller-metrics-auth-role
rules:
- apiGroups:
  - authentication.k8s.io
  resources:
  - tokenreviews
  verbs:
  - create
- apiGroups:
  - authorization.k8s.io
  resources:
  - subjectaccessreviews
  verbs:
  - create
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  labels:
    control-plane: controller-manager
  name: slice-controller-metrics-reader
rules:
- nonResourceURLs:
  - /metrics
  verbs:
  - get
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  labels:
    app.kubernetes.io/managed-by: kustomize
    app.kubernetes.io/name: slice-controller
    control-plane: controller-manager
  name: slice-controller-leader-election-rolebinding
  namespace: slice-controller-system
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: slice-controller-leader-election-role
subjects:
- kind: ServiceAccount
  name: slice-controller-controller-manager
  namespace: slice-controller-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  labels:
    app.kubernetes.io/managed-by: kustomize
    app.kubernetes.io/name: slice-controller
    control-plane: controller-manager
  name: slice-controller-webhook-secrets-rolebinding
  namespace: slice-controller-system
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: slice-controller-webhook-secrets-role
subjects:
- kind: ServiceAccount
  name: slice-controller-controller-manager
  namespace: slice-controller-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  labels:
    app.kubernetes.io/managed-by: kustomize
    app.kubernetes.io/name: slice-controller
    control-plane: controller-manager
  name: slice-controller-manager-rolebinding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: slice-controller-manager-role
subjects:
- kind: ServiceAccount
  name: slice-controller-controller-manager
  namespace: slice-controller-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  labels:
    control-plane: controller-manager
  name: slice-controller-metrics-auth-rolebinding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: slice-controller-metrics-auth-role
subjects:
- kind: ServiceAccount
  name: slice-controller-controller-manager
  namespace: slice-controller-system
---
apiVersion: v1
kind: Secret
metadata:
  labels:
    control-plane: controller-manager
  name: slice-controller-webhook-server-cert
  namespace: slice-controller-system
---
apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/managed-by: kustomize
    app.kubernetes.io/name: slice-controller
    control-plane: controller-manager
  name: slice-controller-controller-manager-metrics-service
  namespace: slice-controller-system
spec:
  ports:
  - name: https
    port: 8443
    protocol: TCP
    targetPort: 8443
  selector:
    app.kubernetes.io/name: slice-controller
    control-plane: controller-manager
---
apiVersion: v1
kind: Service
metadata:
  labels:
    control-plane: controller-manager
  name: slice-controller-webhook-service
  namespace: slice-controller-system
spec:
  ports:
  - port: 443
    protocol: TCP
    targetPort: 9443
  selector:
    control-plane: controller-manager
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/managed-by: kustomize
    app.kubernetes.io/name: slice-controller
    control-plane: controller-manager
  name: slice-controller-controller-manager
  namespace: slice-controller-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: slice-controller
      control-plane: controller-manager
  template:
    metadata:
      annotations:
        kubectl.kubernetes.io/default-container: manager
      labels:
        app.kubernetes.io/name: slice-controller
        control-plane: controller-manager
    spec:
      containers:
      - args:
        - --metrics-bind-address=:8443
        - --leader-elect
        - --health-probe-bind-address=:8081
        - --zap-log-level=3
        - --feature-gates=UseRetryMechanismForSliceCreation=true
        - --activation-timeout=60m
        - --kube-api-qps=100
        - --kube-api-burst=200
        - --default-slice-health-node-affinity=HEALTHY_AND_DEGRADED
        - --reuse-slices=true
        - --add-preferred-node-affinity=true
        command:
        - /manager
        image: tpuongke/kueue-slice-controller:v0.10
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8081
          initialDelaySeconds: 15
          periodSeconds: 20
        name: manager
        ports:
        - containerPort: 9443
          name: webhook-server
          protocol: TCP
        readinessProbe:
          httpGet:
            path: /readyz
            port: 8081
          initialDelaySeconds: 5
          periodSeconds: 10
        resources:
          limits:
            cpu: 12
            memory: 32Gi
          requests:
            cpu: 8
            memory: 16Gi
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop:
            - ALL
        volumeMounts:
        - mountPath: /tmp/k8s-webhook-server/serving-certs
          name: cert
          readOnly: true
      securityContext:
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault
      serviceAccountName: slice-controller-controller-manager
      terminationGracePeriodSeconds: 10
      volumes:
      - name: cert
        secret:
          defaultMode: 420
          secretName: slice-controller-webhook-server-cert
---
apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
  labels:
    control-plane: controller-manager
  name: slice-controller-mutating-webhook-configuration
webhooks:
- admissionReviewVersions:
  - v1
  clientConfig:
    service:
      name: slice-controller-webhook-service
      namespace: slice-controller-system
      path: /mutate-batch-v1-job
  failurePolicy: Fail
  name: mjob.kb.io
  rules:
  - apiGroups:
    - batch
    apiVersions:
    - v1
    operations:
    - CREATE
    resources:
    - jobs
  sideEffects: None
- admissionReviewVersions:
  - v1
  clientConfig:
    service:
      name: slice-controller-webhook-service
      namespace: slice-controller-system
      path: /mutate-jobset-x-k8s-io-v1alpha2-jobset
  failurePolicy: Fail
  name: mjobset.kb.io
  rules:
  - apiGroups:
    - jobset.x-k8s.io
    apiVersions:
    - v1alpha2
    operations:
    - CREATE
    resources:
    - jobsets
  sideEffects: None
- admissionReviewVersions:
  - v1
  clientConfig:
    service:
      name: slice-controller-webhook-service
      namespace: slice-controller-system
      path: /mutate-leaderworkerset-x-k8s-io-v1-leaderworkerset
  failurePolicy: Fail
  name: mleaderworkerset.kb.io
  rules:
  - apiGroups:
    - leaderworkerset.x-k8s.io
    apiVersions:
    - v1
    operations:
    - CREATE
    resources:
    - leaderworkersets
  sideEffects: None
- admissionReviewVersions:
  - v1
  clientConfig:
    service:
      name: slice-controller-webhook-service
      namespace: slice-controller-system
      path: /mutate-ray-io-v1-raycluster
  failurePolicy: Fail
  name: mraycluster.kb.io
  rules:
  - apiGroups:
    - ray.io
    apiVersions:
    - v1
    operations:
    - CREATE
    resources:
    - rayclusters
  sideEffects: None
- admissionReviewVersions:
  - v1
  clientConfig:
    service:
      name: slice-controller-webhook-service
      namespace: slice-controller-system
      path: /mutate-ray-io-v1-rayjob
  failurePolicy: Fail
  name: mrayjob.kb.io
  rules:
  - apiGroups:
    - ray.io
    apiVersions:
    - v1
    operations:
    - CREATE
    resources:
    - rayjobs
  sideEffects: None

  2. Aplica el manifiesto slice-controller.yaml:

    kubectl apply -f slice-controller.yaml

  3. Para configurar Kueue para la segmentación dinámica, guarda el siguiente manifiesto como dynamic-slice-topology.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: kueue.x-k8s.io/v1beta1
kind: Topology
metadata:
  name: superslice-topology
spec:
  levels:
  # Label to identify the physical block a sub-block belongs to.
  # Only sub-blocks from the same block can form a slice.
  - nodeLabel: cloud.google.com/gce-topology-block
  # Label to identify individual TPU sub-blocks (4x4x4 topology).
  - nodeLabel: cloud.google.com/gke-tpu-partition-4x4x4-id
  # Standard Kubernetes label for individual nodes.
  # Required to assign Pods to specific VMs.
  - nodeLabel: kubernetes.io/hostname
---
apiVersion: kueue.x-k8s.io/v1beta1
kind: ResourceFlavor
metadata:
  name: superslice-rf
spec:
  nodeLabels:
    cloud.google.com/gke-tpu-accelerator: tpu7x
  topologyName: superslice-topology
---
apiVersion: kueue.x-k8s.io/v1beta1
kind: AdmissionCheck
metadata:
  name: superslice-ac
spec:
  controllerName: accelerator.gke.io/slice
---
apiVersion: kueue.x-k8s.io/v1beta1
kind: ClusterQueue
metadata:
  name: cq
spec:
  namespaceSelector: {}
  admissionChecks:
  - superslice-ac
  resourceGroups:
  - coveredResources:
    - google.com/tpu
    flavors:
    - name: superslice-rf
      resources:
      - name: google.com/tpu
        nominalQuota: "999999"  # modeling unlimited quota
---
apiVersion: kueue.x-k8s.io/v1beta1
kind: LocalQueue
metadata:
  name: lq
  namespace: default
spec:
  clusterQueue: cq

  4. Aplica el manifiesto dynamic-slice-topology.yaml:

    kubectl apply -f dynamic-slice-topology.yaml

    En este manifiesto, configuras Kueue para la segmentación dinámica definiendo los siguientes recursos:

    • Topología de porción dinámica de Ironwood (TPU7x) (superslice-topology): La topología define los niveles que Kueue considera cuando programa cargas de trabajo de segmentación dinámica. Estos niveles son los siguientes:
      • Etiqueta cloud.google.com/gce-topology-block: este nivel es obligatorio para comprender qué subbloques pertenecen a qué bloques, ya que solo los subbloques del mismo bloque pueden formar un segmento.
      • Etiqueta cloud.google.com/gke-tpu-partition-4x4x4-id: Este nivel representa subbloques individuales de Ironwood (TPU7x) (topología 4x4x4).
      • Etiqueta kubernetes.io/hostname: Este nivel es obligatorio para asignar Pods a VMs específicas y observar sus etiquetas y taints.
    • ResourceFlavor de SuperSlice de Ironwood (TPU7x) (superslice-rf): El tipo de recurso para los subbloques de Ironwood (TPU7x) incluye la etiqueta cloud.google.com/gke-tpu-accelerator: tpu7x para que coincida con los nodos con máquinas de Ironwood (TPU7x).
    • SuperSlice AdmissionCheck (superslice-ac): Esta verificación de admisión le indica a Kueue que no programe una carga de trabajo hasta que el controlador de porciones de GKE confirme que la porción se activó. La verificación de admisión se define primero y, luego, se agrega al ClusterQueue que controla las cargas de trabajo de segmentación dinámica.
    • ClusterQueue (cq) y LocalQueue (lq): Estos campos administran los recursos de google.com/tpu. La ClusterQueue cq incluye la verificación de admisión superslice-ac. El campo nominalQuota de google.com/tpu se puede configurar de dos maneras:
      • Cuota específica: Establece el campo nominalQuota para que coincida con la capacidad existente para el uso compartido equitativo y la administración de cuotas.
      • Cuota ilimitada: Establece el campo nominalQuota en un valor muy alto, como "999999", para modelar una cuota ilimitada. Para enfocarse en TAS y la segmentación dinámica, esta configuración omite la funcionalidad de administración de cuotas de Kueue.

Define la selección del estado de la partición

Más allá del estado y la preparación estándar de los nodos, GKE expone el estado específico de cada forma de partición con la etiqueta cloud.google.com/gke-tpu-partition-[shape]-state (en la que [shape] coincide con la forma del ID de partición, como 2x2x1, 2x2x2, 2x2x4, 2x4x4 o 4x4x4). Esta etiqueta permite que GKE tenga en cuenta los factores que influyen en la formación de porciones, como el estado de los vínculos de TPU. La configuración de subsegmentación dinámica (topologías más pequeñas que 4x4x4) requiere la versión 1.36.0-gke.3712000 o posterior de GKE.

Puedes definir el valor de la etiqueta de estado de la partición de la siguiente manera:

  • HEALTHY: La partición está en buen estado y es completamente funcional.
  • DEGRADED: La infraestructura de la partición se encuentra en un estado degradado, por ejemplo, debido a la degradación del vínculo de OCS. La partición aún puede formar un segmento, pero el rendimiento general puede ser menor en comparación con las particiones en buen estado. Este estado solo se aplica a la topología 4x4x4 de nivel superior. Las topologías más pequeñas no tienen un estado degradado.
  • UNHEALTHY: La partición no está en buen estado y no puede formar una porción.
  • UNSET: El estado no está definido debido a que la inicialización del controlador de porciones de GKE no se realizó correctamente.
  • INCOMPLETE: No se aprovisionan todos los nodos dentro de la partición.

El webhook del controlador de porciones de Kueue valida si una carga de trabajo incluye un requisito de estado de partición específico. Si no se indica ninguna preferencia, el webhook inserta una afinidad de nodo predeterminada.

El comportamiento es el siguiente:

  • Si hay un nodeSelector o nodeAffinity que se orienta a la etiqueta cloud.google.com/gke-tpu-partition-[shape]-state, no se modifica.

  • Si no existe tal configuración de etiqueta, el webhook inserta la siguiente afinidad de nodo predeterminada para garantizar que solo se usen las particiones disponibles:

    nodeAffinity:
  requiredDuringSchedulingIgnoredDuringExecution:
    nodeSelectorTerms:
    - matchExpressions:
      - key: cloud.google.com/gke-tpu-partition-4x4x4-state
        operator: In
        values:
        - "HEALTHY"
        - "DEGRADED"

En la siguiente sección, se incluyen ejemplos en los que la etiqueta cloud.google.com/gke-tpu-partition-4x4x4-state se configura para especificar los diferentes parámetros de configuración de estado de los subbloques.

Ejecuta cargas de trabajo de prueba en la segmentación dinámica con Kueue

En esta sección, se describe cómo implementar cargas de trabajo en la segmentación dinámica con Kueue y TAS. Incluye ejemplos que muestran cómo crear una carga de trabajo de porción dinámica y una carga de trabajo que consta de varias porciones. Las cargas de trabajo se envían como JobSets.

Ejemplo 1: Una sola carga de trabajo usa una sola porción dinámica

En el siguiente ejemplo, se describe cómo crear una carga de trabajo con una porción que tenga una topología 4x12x16, que se compone de 12 subbloques. La cantidad de Pods se calculó de la siguiente manera: (4 * 12 * 16) / 4 chips por nodo = 192 Pods.

  1. Guarda el siguiente manifiesto como big-super-slice.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: big-super-slice
  labels:
    kueue.x-k8s.io/queue-name: lq
spec:
  replicatedJobs:
    - name: job-jax
      replicas: 1
      template:
        spec:
          parallelism: 192  # pods per slice calculation: 4*12*16 / 4 = 192
          completions: 192
          backoffLimit: 10
          template:
            metadata:
              annotations:
                cloud.google.com/gke-tpu-slice-topology: 4x12x16
            spec:
              tolerations:
                - key: "google.com/tpu"
                  operator: "Equal"
                  value: "present"
                  effect: "NoSchedule"
              nodeSelector:
                cloud.google.com/gke-tpu-accelerator: tpu7x
              containers:
                - name: jax
                  image: python:latest
                  command:
                    - bash
                    - -c
                    - |
                      printenv
                      pip install "jax[tpu]" -f https://storage.googleapis.com/jax-releases/libtpu_releases.html
                      python -c 'import jax; print("Global device count:", jax.device_count(), "Local device count:", jax.local_device_count())'
                  resources:
                    limits:
                      google.com/tpu: 4
              restartPolicy: Never

    En este manifiesto, las siguientes anotaciones le indican a Kueue las características y la topología de la porción para configurar lo siguiente:

    • cloud.google.com/gke-tpu-slice-topology: Especifica "4x12x16" como la topología de porción dinámica. Los requisitos para la topología del acelerador tpu7x incluyen las siguientes reglas:
      • Para la división dinámica en porciones secundarias: Puedes especificar topologías más pequeñas que 4x4x4, como 2x2x1, 2x2x2, 2x2x4 o 2x4x4. Estas topologías más pequeñas requieren la versión 1.36.0-gke.3712000 de GKE o una posterior.
      • Para la división dinámica en superporciones: Puedes especificar topologías que sean iguales o superiores a 4x4x4. Para la configuración dinámica de super-slicing, cada dimensión de la topología solicitada debe ser un múltiplo de cuatro, por ejemplo, 4A x 4B x 4C.
      • La topología debe ser una cadena tridimensional con el formato AxBxC, por ejemplo, 4x8x8.
      • Las dimensiones deben ordenarse de forma no decreciente: A <= B <= C. Por ejemplo, 4x8x4 no es válido; debería ser 4x4x8.
      • El producto de las dimensiones (ABC) no debe superar 9,216.
      • Las topologías de porciones más grandes admitidas pueden incluir hasta 32 subbloques. Por ejemplo, 8x16x16 con 32 subbloques,8x12x20 con 30 subbloques o 12x12x12 con 27 subbloques están dentro de los límites aceptados.
    • cloud.google.com/gke-tpu-accelerator: tpu7x: programa Pods en VMs que ejecutan Ironwood (TPU7x).
    • kueue.x-k8s.io/queue-name: asigna el JobSet a una LocalQueue de Kueue.
    • El webhook inserta la afinidad de nodos predeterminada para garantizar que se usen los nodos HEALTHY y DEGRADED.

  2. Aplica el manifiesto big-super-slice.yaml:

    kubectl apply -f big-super-slice.yaml

    Después de aplicar el manifiesto, Kueue crea un JobSet llamado big-super-slice. Luego, Kueue intenta formar una sola porción dinámica con una topología 4x12x16. Después de que el segmento se activa, Kueue admite la carga de trabajo y los 192 Pods se programan en los nodos para formar el segmento dinámico que ejecuta tus cargas de trabajo.

Ejemplo 2: Carga de trabajo con más de una réplica

En el siguiente ejemplo, se muestra cómo crear una carga de trabajo que use dos segmentaciones dinámicas, cada una compuesta por cuatro subbloques que se orienten solo a nodos HEALTHY.

  1. Guarda el siguiente manifiesto como two-super-slices.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: two-super-slices
  labels:
    kueue.x-k8s.io/queue-name: lq
spec:
  replicatedJobs:
    - name: job-jax
      replicas: 2
      template:
        spec:
          parallelism: 64  # Pods per slice calculation: (4*8*8) / 4 = 64
          completions: 64
          backoffLimit: 10
          template:
            metadata:
              annotations:
                cloud.google.com/gke-tpu-slice-topology: 4x8x8
            spec:
              tolerations:
                - key: "google.com/tpu"
                  operator: "Equal"
                  value: "present"
                  effect: "NoSchedule"
              nodeSelector:
                cloud.google.com/gke-tpu-accelerator: tpu7x
                cloud.google.com/gke-tpu-partition-4x4x4-state: "HEALTHY"
              containers:
                - name: jax
                  image: python:latest
                  command:
                    - bash
                    - -c
                    - |
                      printenv
                      pip install "jax[tpu]" -f https://storage.googleapis.com/jax-releases/libtpu_releases.html
                      python -c 'import jax; print("Global device count:", jax.device_count(), "Local device count:", jax.local_device_count())'
                  resources:
                    limits:
                      google.com/tpu: 4
              restartPolicy: Never

  2. Aplica el manifiesto two-super-slices.yaml:

    kubectl apply -f two-super-slices.yaml

En este manifiesto, debes establecer el campo replicas en 2 en la sección replicatedJobs. Después de aplicar el manifiesto, Kueue intenta formar dos porciones separadas con una topología 4x8x8. Kueue crea una segmentación dinámica para cada réplica definida en jobset.spec.replicatedJobs[].replicas. Si se especifican n réplicas, Kueue crea n porciones dinámicas para la carga de trabajo y espera a que todas las porciones se activen antes de admitir la carga de trabajo.

Optimiza la programación de cargas de trabajo con la reutilización de porciones

De forma predeterminada, Kueue le indica al controlador de porciones que aprovisione una porción de TPU nueva para cada ejecución de carga de trabajo y que la borre cuando se complete la carga de trabajo. Este comportamiento puede generar deserción y sobrecarga en la infraestructura subyacente.

Con la reutilización de porciones, las cargas de trabajo nuevas pueden reutilizar porciones de TPU existentes y que estén inactivas, que tengan una topología y límites de hardware idénticos. Cuando habilitas la reutilización de porciones, Kueue marca la porción como inactiva al final de un trabajo en lugar de borrarla. Un trabajo nuevo que solicita la misma partición reclama y reutiliza la porción de forma instantánea, lo que evita el retraso en el aprovisionamiento del hardware.

Habilita la reutilización de porciones

Para optimizar por completo la reutilización de porciones, debes configurar el controlador de Slice y Kueue para que funcionen juntos.

  1. Configura el controlador de porciones: Actualiza los argumentos de implementación del controlador de porciones de Kueue para incluir la marca --reuse-slices=true. Para garantizar que las cargas de trabajo se programen de forma óptima en los segmentos existentes, agrega también la marca --add-preferred-node-affinity=true.

  2. Configura Kueue (recomendado): Para permitir que Kueue use las sugerencias de afinidad de nodos preferidas del controlador, debes habilitar el interruptor de función TASRespectNodeAffinityPreferred en tu configuración de Kueue.

    Por ejemplo, edita el ConfigMap kueue-manager-config para agregar el interruptor de función:

    apiVersion: v1
kind: ConfigMap
metadata:
  name: kueue-manager-config
  namespace: kueue-system
data:
  controller_manager_config.yaml: |
    apiVersion: config.kueue.x-k8s.io/v1beta1
    kind: Configuration
    featureGates:
      TASRespectNodeAffinityPreferred: true
    # ...

    Después de cambiar el ConfigMap, reinicia el Deployment de kueue-controller-manager para aplicar el cambio:

    kubectl rollout restart deploy kueue-controller-manager -n kueue-system

Aplicar la eliminación de porciones por carga de trabajo

Para que una carga de trabajo específica limpie sus porciones y evite que se vuelvan a usar, completa los siguientes pasos:

  1. Aplica la siguiente etiqueta a tu definición de Job o JobSet:

    kueue.gke.io/tpu-enforce-slice-deletion: "true"

    Después de aplicar esta etiqueta, la carga de trabajo se puede programar en una porción inactiva existente. Sin embargo, después de que se complete la carga de trabajo, la porción se borrará de forma permanente en lugar de devolverse al grupo reutilizable.

  2. Configura Kueue para que pase esta etiqueta del trabajo del framework al objeto Workload de Kueue. Para ello, agrega la etiqueta a la lista labelKeysToCopy en tu configuración de Kueue:

    labelKeysToCopy:
- "kueue.gke.io/tpu-enforce-slice-deletion"

Supervisa la porción

Puedes ver el estado de la porción y supervisar sus métricas con las métricas del sistema de GKE.

Supervisa el estado de la porción

Cuando una carga de trabajo crea o usa de forma activa una porción, el controlador de porciones adjunta etiquetas para identificar la carga de trabajo que la usa. Debido a que los nombres de Slice se generan de forma dinámica (y se desvinculan del nombre de la carga de trabajo cuando se habilita la reutilización), debes usar estas etiquetas para encontrar el Slice asignado a tu carga de trabajo.

  1. Para encontrar los segmentos asignados a una carga de trabajo, ejecuta el siguiente comando:

    kubectl get slice -l kueue.gke.io/tpu-slice-used-by-namespace=NAMESPACE,kueue.gke.io/tpu-slice-used-by-workload=WORKLOAD_NAME

    Reemplaza lo siguiente:

    • NAMESPACE: el espacio de nombres de tu carga de trabajo.
    • WORKLOAD_NAME: Es el nombre de la carga de trabajo de Kueue, que suele ser el mismo que el del objeto Job o JobSet.

  2. Copia el nombre de la porción del resultado del comando anterior.

  3. Usa el nombre de la porción para verificar el estado detallado de tu porción dinámica:

    kubectl describe slice SLICE_NAME

    Reemplaza SLICE_NAME por el nombre de tu porción.

El resultado es similar a lo siguiente:

Name:         s-4x4x4-74d3fb0b
Namespace:
Labels:       <none>
Annotations:  <none>
API Version:  accelerator.gke.io/v1beta1
Kind:         Slice
Metadata:
  Creation Timestamp:  2026-02-12T23:44:28Z
  Finalizers:
    accelerator.gke.io/slice-finalizer
  Generation:        1
  Resource Version:  1770939905695871008
  UID:               6dbbfe14-4486-4462-864d-e078d0ca8b5b
Spec:
  Partition Ids:
    5eae6a4f59d59cf30a9bf49de618eb2b
  Topology:  4x4x4
  Type:      tpu7x
Status:
  Conditions:
    Last Transition Time:  2026-02-12T23:45:05Z
    Message:
    Reason:                ACTIVE
    Status:                True
    Type:                  Ready
    Last Transition Time:  2026-02-12T23:45:05Z
    Message:               NodeLabelingCompleted
    Reason:                NodeLabelIsAdded
    Status:                True
    Type:                  NodeLabeled
Events:                    <none>

Supervisa las métricas de la porción

Puedes supervisar las siguientes métricas del sistema de GKE que exponen la condición de una porción:

  • kubernetes.io/accelerator/slice/state
  • kubernetes.io/accelerator/partition/state
  • kubernetes.io/accelerator/slice/deformation_durations
  • kubernetes.io/accelerator/slice/formation_durations

Para obtener más información sobre las métricas, consulta Métricas del sistema de GKE.

Métricas del controlador de Slice de Kueue

También puedes supervisar las siguientes métricas de Prometheus que expone el controlador de porciones de Kueue para observar el ciclo de vida, la reutilización y las verificaciones de admisión de las porciones:

Métricas del ciclo de vida de Slice

Las métricas del ciclo de vida de Slice hacen un seguimiento de la creación y eliminación de segmentos:

  • tpu_ac_slice_create_time: Es un histograma que mide cuánto tiempo tardó la creación de porciones.
  • tpu_ac_slices_created: Contador que hace un seguimiento de los segmentos creados (incluye una etiqueta is_reusable).
  • tpu_ac_slices_status: Es un indicador que hace un seguimiento de la cantidad actual de porciones por estado, incluidas las etiquetas is_reusable y in_use.
  • tpu_ac_slice_delete_time: Es un histograma que mide cuánto tiempo tardó en borrarse la porción.
  • tpu_ac_slices_deleted: Contador que hace un seguimiento de las porciones borradas.
  • tpu_ac_slices_gc: El seguimiento de contadores limpió automáticamente los segmentos.

Métricas de reutilización de porciones

Las métricas de reutilización de Slice realizan un seguimiento de la reutilización exitosa y los conflictos de las porciones de TPU:

  • tpu_ac_slices_reused: Contador que hace un seguimiento de las porciones reutilizadas correctamente.
  • tpu_ac_slices_conflict: Indica las porciones de seguimiento de contadores que se borraron debido a discrepancias de topología o forma.

Métricas de carga de trabajo y admisión

Las métricas de carga de trabajo y admisión realizan un seguimiento de la duración y los resultados de las verificaciones de admisión:

  • tpu_ac_admission_time: Es un histograma que mide la duración del proceso de verificación de admisión. Nota: Esto mide la duración de la verificación de admisión del controlador de porciones y no incluye el tiempo general de admisión de la carga de trabajo de Kueue.
  • tpu_ac_workload_processed: Es el contador de decisiones de verificación de admisión, que contiene una etiqueta target_state.

Métricas generales

Las métricas generales realizan un seguimiento de los problemas y errores operativos:

  • tpu_ac_problem: Es un contador que hace un seguimiento de los problemas o errores operativos. Esta métrica incluye una etiqueta problem que indica el tipo de error específico.

Realiza una limpieza

Para evitar cargos inesperados, borra tus porciones antes de borrar los grupos de nodos.

  1. Borra el JobSet. Esta acción activa Kueue para borrar los recursos personalizados de Slice asociados.

    kubectl delete jobset JOBSET_NAME

    Reemplaza JOBSET_NAME por el nombre de tu JobSet, por ejemplo, big-super-slice.

  2. Borra el grupo de nodo TPU:

    gcloud container node-pools delete NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION

Usa la segmentación dinámica con tu propio programador (opcional)

Este documento se enfoca en el uso de Kueue y TAS. Sin embargo, también puedes administrar la segmentación dinámica con tu propio programador personalizado. Si eliges usar un programador diferente, sigue la información de referencia del recurso personalizado Slice.

¿Qué sigue?