From 4ac9df5e042f75ab6898c458c6c8a9249412c0e6 Mon Sep 17 00:00:00 2001 From: windsonsea Date: Thu, 25 Dec 2025 14:28:51 +0800 Subject: [PATCH] [zh] Add Kueue docs Signed-off-by: windsonsea --- .../userguide/Kueue/examples/defalt_use.md | 85 ++++++ .../userguide/Kueue/how-to-use-kueue.md | 273 ++++++++++++++++++ sidebars.js | 2 +- 3 files changed, 359 insertions(+), 1 deletion(-) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/userguide/Kueue/examples/defalt_use.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/userguide/Kueue/how-to-use-kueue.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/userguide/Kueue/examples/defalt_use.md b/i18n/zh/docusaurus-plugin-content-docs/current/userguide/Kueue/examples/defalt_use.md new file mode 100644 index 0000000..bd693df --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/userguide/Kueue/examples/defalt_use.md @@ -0,0 +1,85 @@ +--- +title: 默认 Kueue 使用示例 +--- + +本示例演示了如何将 Kueue 与 HAMi vGPU 资源配合使用。示例包含一套完整的配置，用于创建 +ResourceFlavor、ClusterQueue、LocalQueue，以及一个请求 vGPU 资源的示例 Deployment。 + +在应用此示例之前，请确保已安装 HAMi 和 Kueue，并且已在 Kueue 中启用 ResourceTransformation +配置（参见 [如何在 HAMi 上使用 Kueue](../how-to-use-kueue.md)）。 + +```yaml +apiVersion: kueue.x-k8s.io/v1beta1 +kind: ResourceFlavor +metadata: + name: hami-flavor +spec: + nodeLabels: + gpu: "on" +--- +apiVersion: kueue.x-k8s.io/v1beta1 +kind: ClusterQueue +metadata: + name: hami-queue +spec: + namespaceSelector: {} + resourceGroups: + - coveredResources: + - nvidia.com/gpu + - nvidia.com/total-gpucores + - nvidia.com/total-gpumem + flavors: + - name: hami-flavor + resources: + - name: nvidia.com/gpu + nominalQuota: 20 + - name: nvidia.com/total-gpucores + nominalQuota: 600 + - name: nvidia.com/total-gpumem + nominalQuota: 20480 +--- +apiVersion: v1 +kind: Namespace +metadata: + name: kueue-test +--- +apiVersion: kueue.x-k8s.io/v1beta1 +kind: LocalQueue +metadata: + name: user-queue + namespace: kueue-test +spec: + clusterQueue: "hami-queue" +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: gpu-burn + namespace: kueue-test + labels: + kueue.x-k8s.io/queue-name: user-queue +spec: + replicas: 1 + selector: + matchLabels: + app-name: gpu-burn + template: + metadata: + labels: + app-name: gpu-burn + spec: + containers: + - args: + - while :; do /app/gpu_burn 300 || true; sleep 300; done + command: + - /bin/sh + - -lc + image: oguzpastirmaci/gpu-burn:latest + imagePullPolicy: IfNotPresent + name: main + resources: + limits: + nvidia.com/gpu: "2" # 请求 2 个 vGPU 实例 + nvidia.com/gpucores: "30" # 每个 vGPU 为 30 核 + nvidia.com/gpumem: "1024" # 每个 vGPU 为 1024 MiB +``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/userguide/Kueue/how-to-use-kueue.md b/i18n/zh/docusaurus-plugin-content-docs/current/userguide/Kueue/how-to-use-kueue.md new file mode 100644 index 0000000..88a1527 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/userguide/Kueue/how-to-use-kueue.md @@ -0,0 +1,273 @@ +--- +title: 如何在 HAMi 上使用 Kueue +--- + +# 在 HAMi 中使用 Kueue + +本指南将帮助你使用 Kueue 来管理 HAMi vGPU 资源，包括启用 Deployment 支持、配置 +ResourceTransformation，以及创建请求 vGPU 资源的工作负载。 + +## 前置条件 + +在开始之前，请确保： + +- 集群中已安装 HAMi +- 集群中已安装 Kueue + +## 快速开始 + +### 安装 Kueue + +如果尚未安装 Kueue，可以使用以下命令进行安装： + +```bash +kubectl apply --server-side -f https://github.com/kubernetes-sigs/kueue/releases/download/v0.15.0/manifests.yaml +``` + +安装完成后，Kueue 控制器将运行在 `kueue-system` 命名空间中。 + +## 在 Kueue 中启用 Deployment 支持 + +Kueue 支持管理 Deployment，但你需要在 Kueue 配置中启用 `deployment` 集成。 + +### 配置 Kueue + +编辑 Kueue manager 的配置以启用 Deployment 支持： + +```bash +kubectl edit configmap kueue-manager-config -n kueue-system +``` + +添加如下配置： + +```yaml +apiVersion: config.kueue.x-k8s.io/v1beta2 +kind: Configuration +integrations: + frameworks: + - "deployment" + - "pod" +``` + +更新配置后，重启 kueue-manager： + +```bash +kubectl rollout restart deployment kueue-manager -n kueue-system +``` + +## 配置 ResourceTransformation + +ResourceTransformation 允许 Kueue 将一种形式的资源请求转换为另一种形式。 +对于 HAMi vGPU 资源，这使得 Kueue 可以使用聚合指标 +（如 `nvidia.com/total-gpucores` 和 `nvidia.com/total-gpumem`）来跟踪 GPU 资源， +而不是单独的 `nvidia.com/gpu` 请求。 + +编辑 kueue-manager 配置以添加 ResourceTransformation： + +```bash +kubectl edit configmap kueue-manager-config -n kueue-system +``` + +将 ResourceTransformation 配置添加到同一个 Configuration 对象中： + +```yaml +apiVersion: config.kueue.x-k8s.io/v1beta2 +kind: Configuration +integrations: + frameworks: + - "deployment" + - "pod" +resources: + transformations: + - input: nvidia.com/gpucores + strategy: Replace + multiplyBy: nvidia.com/gpu + outputs: + nvidia.com/total-gpucores: "1" + - input: nvidia.com/gpumem + strategy: Replace + multiplyBy: nvidia.com/gpu + outputs: + nvidia.com/total-gpumem: "1" +``` + +更新配置后，重启 kueue-manager： + +```bash +kubectl rollout restart deployment kueue-manager -n kueue-system +``` + +### 创建 ResourceFlavor + +首先，创建一个 ResourceFlavor： + +```yaml +apiVersion: kueue.x-k8s.io/v1beta2 +kind: ResourceFlavor +metadata: + name: hami-flavor +spec: + nodeLabels: + gpu: "on" +``` + +该 ResourceFlavor 仅适用于启用了 vGPU 功能的节点。 + +### 创建 ClusterQueue + +创建一个用于跟踪 HAMi 资源的 ClusterQueue： + +```yaml +apiVersion: kueue.x-k8s.io/v1beta2 +kind: ClusterQueue +metadata: + name: hami-queue +spec: + resourceGroups: + - coveredResources: ["nvidia.com/gpu", "nvidia.com/total-gpucores", "nvidia.com/total-gpumem"] + flavors: + - name: hami-flavor + resources: + - name: "nvidia.com/gpu" + nominalQuota: 80 + - name: "nvidia.com/total-gpucores" + nominalQuota: 200 + - name: "nvidia.com/total-gpumem" + nominalQuota: 10240 +``` + +该 ClusterQueue 跟踪以下资源： + +* `nvidia.com/total-gpucores`：所有 vGPU 的 GPU 核心总量（每个单位表示 1% 的 GPU 核心） +* `nvidia.com/total-gpumem`：所有 vGPU 的 GPU 显存总量（单位为 MiB） + +### 创建 LocalQueue + +创建一个引用该 ClusterQueue 的 LocalQueue： + +```yaml +apiVersion: kueue.x-k8s.io/v1beta2 +kind: LocalQueue +metadata: + name: hami-local-queue + namespace: default +spec: + clusterQueue: hami-queue +``` + +## 创建请求 vGPU 资源的工作负载 + +现在，你可以创建请求 vGPU 资源的 Deployment。 +Kueue 将通过 ResourceTransformation 自动转换资源请求。 + +### 基础 vGPU Deployment + +下面是一个请求 vGPU 资源的 Deployment 示例： + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: vgpu-deployment + labels: + app: vgpu-app + kueue.x-k8s.io/queue-name: hami-local-queue +spec: + replicas: 2 + selector: + matchLabels: + app: vgpu-app + template: + metadata: + labels: + app: vgpu-app + spec: + containers: + - name: vgpu-container + image: nvidia/cuda:11.8.0-base-ubuntu22.04 + command: ["sleep", "infinity"] + resources: + limits: + nvidia.com/gpu: 1 + nvidia.com/gpucores: 50 + nvidia.com/gpumem: 1024 +``` + +在该示例中： + +* `kueue.x-k8s.io/queue-name` 标签将 Deployment 关联到 `hami-local-queue` +* `nvidia.com/gpu: 1` 请求 1 个 vGPU +* `nvidia.com/gpucores: 50` 为每个 vGPU 请求 50% 的 GPU 核心 +* `nvidia.com/gpumem: 1024` 为每个 vGPU 请求 1024 MiB 的 GPU 显存 + +### 请求多个 vGPU 的 Deployment + +你也可以创建一个请求多个 vGPU 的 Deployment： + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: multi-vgpu-deployment + labels: + app: multi-vgpu-app + kueue.x-k8s.io/queue-name: hami-local-queue +spec: + replicas: 1 + selector: + matchLabels: + app: multi-vgpu-app + template: + metadata: + labels: + app: multi-vgpu-app + spec: + containers: + - name: vgpu-container + image: nvidia/cuda:11.8.0-base-ubuntu22.04 + command: ["sleep", "infinity"] + resources: + limits: + nvidia.com/gpu: 2 + nvidia.com/gpucores: 30 + nvidia.com/gpumem: 1024 +``` + +该 Deployment 请求 2 个 vGPU，每个 vGPU 分配 30% 的 GPU 核心和 1024 MiB 的 GPU 显存。 + +## 验证资源使用情况 + +要检查 ClusterQueue 中的资源使用情况，可以查看 `status.flavorsReservation` 字段： + +```bash +kubectl get clusterqueue hami-queue -o yaml +``` + +`status.flavorsReservation` 显示当前的资源消耗情况： + +```yaml +status: + flavorsReservation: + - name: hami-flavor + resources: + - name: nvidia.com/total-gpucores + total: "160" # 当前使用量：(2 个副本 × 1 GPU × 50 核心) + (1 个副本 × 2 GPU × 30 核心) = 160 + - name: nvidia.com/total-gpumem + total: "4096" # 当前使用量：(2 个副本 × 1 GPU × 1024 MiB) + (1 个副本 × 2 GPU × 1024 MiB) = 4096 +``` + +## Resource Transformation 细节 + +Kueue 的 ResourceTransformation 会自动转换 HAMi vGPU 的资源请求： + +* `nvidia.com/gpu` × `nvidia.com/gpucores` → `nvidia.com/total-gpucores` +* `nvidia.com/gpu` × `nvidia.com/gpumem` → `nvidia.com/total-gpumem` + +例如： + +* 一个 Deployment 有 2 个副本，每个副本请求 `nvidia.com/gpu: 1`、`nvidia.com/gpucores: 50` 和 `nvidia.com/gpumem: 1024` +* 将消耗：`nvidia.com/total-gpucores: 100`（2 个副本 × 1 GPU × 50 核心）以及 `nvidia.com/total-gpumem: 2048`（2 个副本 × 1 GPU × 1024 MiB） + +## 示例 + +完整可运行示例请参见 [示例文件](./examples/defalt_use.md)。 diff --git a/sidebars.js b/sidebars.js index 3564c81..2e99c2d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -268,7 +268,7 @@ module.exports = { }, { "type": "category", - "label": "Usring HAMi with Kueue", + "label": "Using HAMi with Kueue", "items": [ "userguide/Kueue/how-to-use-kueue", {