本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # SageMaker HyperPod 任務治理 SageMaker HyperPod 任務治理是強大的管理系統，旨在簡化資源配置，並確保 Amazon EKS 叢集跨團隊和專案有效利用運算資源。這讓管理員能夠設定： + 各種任務的優先順序層級 + 每個團隊的運算配置 + 每個團隊如何借出和借入閒置運算 + 如果團隊先佔自己的任務 HyperPod 任務治理也提供 Amazon EKS 叢集可觀測性，提供叢集容量的即時可見性。這包括運算可用性和使用情況、團隊配置和使用率，以及任務執行和等待時間資訊，讓您為明智的決策和主動資源管理做好準備。 下列各節涵蓋如何設定、了解關鍵概念，以及為您的 Amazon EKS 叢集使用 HyperPod 任務治理。 **Topics** + [SageMaker HyperPod 任務治理的設定](sagemaker-hyperpod-eks-operate-console-ui-governance-setup.md) + [儀表板](sagemaker-hyperpod-eks-operate-console-ui-governance-metrics.md) + [任務​](sagemaker-hyperpod-eks-operate-console-ui-governance-tasks.md) + [政策](sagemaker-hyperpod-eks-operate-console-ui-governance-policies.md) + [HyperPod 任務控管 AWS CLI 命令範例](sagemaker-hyperpod-eks-operate-console-ui-governance-cli.md) + [疑難排解](sagemaker-hyperpod-eks-operate-console-ui-governance-troubleshoot.md) + [Amazon SageMaker HyperPod 任務治理的歸因文件](sagemaker-hyperpod-eks-operate-console-ui-governance-attributions.md) # SageMaker HyperPod 任務治理的設定 下一節提供如何開始使用 Amazon CloudWatch 可觀測性 EKS 和 SageMaker HyperPod 任務治理附加元件的相關資訊。 確保您在[叢集管理員的 IAM 使用者](sagemaker-hyperpod-prerequisites-iam.md#sagemaker-hyperpod-prerequisites-iam-cluster-admin)中對 HyperPod 叢集管理員具有最低許可政策搭配 Amazon EKS。這包括執行 SageMaker HyperPod 核心 APIs和管理 內 SageMaker HyperPod 叢集的許可 AWS 帳戶，以及執行 中的任務[管理由 Amazon EKS 協作的 SageMaker HyperPod 叢集](sagemaker-hyperpod-eks-operate.md)。 **Topics** + [儀表板設定](sagemaker-hyperpod-eks-operate-console-ui-governance-setup-dashboard.md) + [任務治理設定](sagemaker-hyperpod-eks-operate-console-ui-governance-setup-task-governance.md) # 儀表板設定 使用以下資訊來開始使用 Amazon SageMaker HyperPod Amazon CloudWatch 可觀測性 EKS 附加元件。這讓您開始使用詳細的視覺化儀表板，檢視 EKS 叢集硬體、團隊配置和任務的指標。 如果您在設定時遇到問題，請參閱 [疑難排解](sagemaker-hyperpod-eks-operate-console-ui-governance-troubleshoot.md) 以取得已知的故障診斷解決方案。 **Topics** + [HyperPod Amazon CloudWatch 可觀測性 EKS 附加元件先決條件](#hp-eks-dashboard-prerequisites) + [HyperPod Amazon CloudWatch 可觀測性 EKS 附加元件設定](#hp-eks-dashboard-setup) ## HyperPod Amazon CloudWatch 可觀測性 EKS 附加元件先決條件 下節包含安裝 Amazon EKS 可觀測性附加元件之前所需的先決條件。 + 確保您在 [叢集管理員的 IAM 使用者](sagemaker-hyperpod-prerequisites-iam.md#sagemaker-hyperpod-prerequisites-iam-cluster-admin) 中具有 HyperPod 叢集管理員的最低許可政策。 + 將 `CloudWatchAgentServerPolicy` IAM 政策連接至您的工作節點。若要執行此作業，請輸入以下命令。將 `my-worker-node-role` 取代為 Kubernetes 工作節點使用的 IAM 角色。 ``` aws iam attach-role-policy \ --role-name my-worker-node-role \ --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy ``` ## HyperPod Amazon CloudWatch 可觀測性 EKS 附加元件設定 使用下列選項來設定 Amazon SageMaker HyperPod Amazon CloudWatch 可觀測性 EKS 附加元件。 ------ #### [ Setup using the SageMaker AI console ] 設定和視覺化 HyperPod 任務治理儀表板需要下列許可。本節擴充了[叢集管理員的 IAM 使用者](sagemaker-hyperpod-prerequisites-iam.md#sagemaker-hyperpod-prerequisites-iam-cluster-admin)中列出的許可。 若要管理任務治理，請使用範例政策： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sagemaker:ListClusters", "sagemaker:DescribeCluster", "sagemaker:ListComputeQuotas", "sagemaker:CreateComputeQuota", "sagemaker:UpdateComputeQuota", "sagemaker:DescribeComputeQuota", "sagemaker:DeleteComputeQuota", "sagemaker:ListClusterSchedulerConfigs", "sagemaker:DescribeClusterSchedulerConfig", "sagemaker:CreateClusterSchedulerConfig", "sagemaker:UpdateClusterSchedulerConfig", "sagemaker:DeleteClusterSchedulerConfig", "eks:ListAddons", "eks:CreateAddon", "eks:DescribeAddon", "eks:DescribeCluster", "eks:DescribeAccessEntry", "eks:ListAssociatedAccessPolicies", "eks:AssociateAccessPolicy", "eks:DisassociateAccessPolicy" ], "Resource": "*" } ] } ``` ------ 若要授予許可來管理 Amazon CloudWatch 可觀測性 Amazon EKS，並透過 SageMaker AI 主控台檢視 HyperPod 叢集儀表板，請使用下列範例政策： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "eks:ListAddons", "eks:CreateAddon", "eks:UpdateAddon", "eks:DescribeAddon", "eks:DescribeAddonVersions", "sagemaker:DescribeCluster", "sagemaker:DescribeClusterNode", "sagemaker:ListClusterNodes", "sagemaker:ListClusters", "sagemaker:ListComputeQuotas", "sagemaker:DescribeComputeQuota", "sagemaker:ListClusterSchedulerConfigs", "sagemaker:DescribeClusterSchedulerConfig", "eks:DescribeCluster", "cloudwatch:GetMetricData", "eks:AccessKubernetesApi" ], "Resource": "*" } ] } ``` ------ 導覽至 SageMaker HyperPod 主控台中的**儀表板**索引標籤，以安裝 Amazon CloudWatch 可觀測性 EKS。若要確保任務治理相關指標包含在**儀表板**中，請啟用 Kueue 指標核取方塊。啟用 Kueue 指標可在達到免費層限制之後啟用 CloudWatch **指標**成本。如需詳細資訊，請參閱 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing/)中的**指標**。 ------ #### [ Setup using the EKS AWS CLI ] 使用下列 EKS AWS CLI 命令來安裝附加元件： ``` aws eks create-addon --cluster-name cluster-name --addon-name amazon-cloudwatch-observability --configuration-values "configuration json" ``` 以下是組態值的 JSON 範例： ``` { "agent": { "config": { "logs": { "metrics_collected": { "kubernetes": { "kueue_container_insights": true, "enhanced_container_insights": true }, "application_signals": { } } }, "traces": { "traces_collected": { "application_signals": { } } } }, }, } ``` ------ #### [ Setup using the EKS Console UI ] 1. 導覽至 [EKS 主控台](https://console.aws.amazon.com/eks/home#/clusters)。 1. 選擇您的叢集。 1. 選擇**附加元件**。 1. 尋找 **Amazon CloudWatch 可觀測性**附加元件並安裝。為附加元件安裝版本 >= 2.4.0。 1. 包括下列 JSON 組態值： ``` { "agent": { "config": { "logs": { "metrics_collected": { "kubernetes": { "kueue_container_insights": true, "enhanced_container_insights": true }, "application_signals": { } }, }, "traces": { "traces_collected": { "application_signals": { } } } }, }, } ``` ------ 一旦成功安裝了 EKS 可觀測性附加元件，您就可以在 HyperPod 主控台**儀表板**索引標籤下檢視 EKS 叢集指標。 # 任務治理設定 本節包括如何設定 Amazon SageMaker HyperPod 任務治理 EKS 附加元件的相關資訊。這包括授予許可，允許您設定任務優先順序、團隊的運算配置、如何共用閒置運算，以及團隊的任務先佔。 如果您在設定時遇到問題，請參閱 [疑難排解](sagemaker-hyperpod-eks-operate-console-ui-governance-troubleshoot.md) 以取得已知的故障診斷解決方案。 **Topics** + [Kueue 設定](#hp-eks-task-governance-kueue-settings) + [HyperPod 任務治理先決條件](#hp-eks-task-governance-prerequisites) + [HyperPod 任務治理設定](#hp-eks-task-governance-setup) ## Kueue 設定 HyperPod 任務治理 EKS 附加元件會為您的 HyperPod EKS 叢集安裝 [Kueue](https://github.com/kubernetes-sigs/kueue/tree/main/apis/kueue)。Kueue 是一種 kubernetes 原生系統，其會管理配額以及任務如何使用這些配額。 | EKS HyperPod 任務治理附加元件版本 | 做為附加元件一部分安裝的 Kueue 版本 | | --- | --- | | v1.1.3 | v0.12.0 | **注意** Kueue v.012.0 及更新版本不包括 kueue-rbac-proxy 做為安裝的一部分。舊版可能已安裝 kueue-rbac-proxy。例如，如果您使用的是 Kueue v0.8.1，您可能具有 kueue-rbac-proxy v0.18.1。 HyperPod 任務治理會利用 Kueue 進行 Kubernetes 原生任務佇列、排程和配額管理，並與 HyperPod 任務治理 EKS 附加元件一起安裝。安裝時，HyperPod 會建立和修改 SageMaker AI 管理的 Kubernetes 資源，例如 `KueueManagerConfig`、`ClusterQueues`、`LocalQueues`、`WorkloadPriorityClasses`、`ResourceFlavors` 和 `ValidatingAdmissionPolicies`。雖然 Kubernetes 管理員可以靈活地修改這些資源的狀態，但對 SageMaker AI 管理的資源所做的任何變更都可能會被服務更新和覆寫。 以下資訊概述 HyperPod 任務治理附加元件使用的組態設定，用於設定 Kueue。 ``` apiVersion: config.kueue.x-k8s.io/v1beta1 kind: Configuration health: healthProbeBindAddress: :8081 metrics: bindAddress: :8443 enableClusterQueueResources: true webhook: port: 9443 manageJobsWithoutQueueName: false leaderElection: leaderElect: true resourceName: c1f6bfd2.kueue.x-k8s.io controller: groupKindConcurrency: Job.batch: 5 Pod: 5 Workload.kueue.x-k8s.io: 5 LocalQueue.kueue.x-k8s.io: 1 ClusterQueue.kueue.x-k8s.io: 1 ResourceFlavor.kueue.x-k8s.io: 1 clientConnection: qps: 50 burst: 100 integrations: frameworks: - "batch/job" - "kubeflow.org/mpijob" - "ray.io/rayjob" - "ray.io/raycluster" - "jobset.x-k8s.io/jobset" - "kubeflow.org/mxjob" - "kubeflow.org/paddlejob" - "kubeflow.org/pytorchjob" - "kubeflow.org/tfjob" - "kubeflow.org/xgboostjob" - "pod" - "deployment" - "statefulset" - "leaderworkerset.x-k8s.io/leaderworkerset" podOptions: namespaceSelector: matchExpressions: - key: kubernetes.io/metadata.name operator: NotIn values: [ kube-system, kueue-system ] fairSharing: enable: true preemptionStrategies: [LessThanOrEqualToFinalShare, LessThanInitialShare] resources: excludeResourcePrefixes: [] ``` 如需每個組態項目的詳細資訊，請參閱 Kueue 文件中的[組態](https://kueue.sigs.k8s.io/docs/reference/kueue-config.v1beta1/#Configuration)。 ## HyperPod 任務治理先決條件 + 確保您在 [叢集管理員的 IAM 使用者](sagemaker-hyperpod-prerequisites-iam.md#sagemaker-hyperpod-prerequisites-iam-cluster-admin) 中具有 HyperPod 叢集管理員的最低許可政策。這包括執行 SageMaker HyperPod 核心 APIs、在 中管理 SageMaker HyperPod 叢集 AWS 帳戶，以及在 中執行任務的許可[管理由 Amazon EKS 協作的 SageMaker HyperPod 叢集](sagemaker-hyperpod-eks-operate.md)。 + 您需要讓 Kubernetes 版本 >= 1.30。如需指示，請參閱[將現有叢集更新為新的 Kubernetes 版本](https://docs.aws.amazon.com/eks/latest/userguide/update-cluster.html)。 + 如果您已在其叢集中安裝 Kueue，請在安裝 EKS 附加元件之前解除安裝 Kueue。 + HyperPod 節點必須已存在於 EKS 叢集中，然後才能安裝 HyperPod 任務治理附加元件。 ## HyperPod 任務治理設定 以下提供如何開始使用 HyperPod 任務治理的相關資訊。 ------ #### [ Setup using the SageMaker AI console ] 以下提供如何使用 SageMaker HyperPod 主控台開始使用 HyperPod 任務治理的相關資訊。 如果您已授予管理 Amazon CloudWatch 可觀測性 EKS 的許可，並透過 [HyperPod Amazon CloudWatch 可觀測性 EKS 附加元件設定](sagemaker-hyperpod-eks-operate-console-ui-governance-setup-dashboard.md#hp-eks-dashboard-setup) 中的 SageMaker AI 主控台檢視 HyperPod 叢集儀表板，則您已連接下列所有許可。如果您尚未設定，請使用以下範例政策授予管理 HyperPod 任務治理附加元件的許可，並透過 SageMaker AI 主控台檢視 HyperPod 叢集儀表板。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "eks:ListAddons", "eks:CreateAddon", "eks:UpdateAddon", "eks:DescribeAddon", "eks:DescribeAddonVersions", "sagemaker:DescribeCluster", "sagemaker:DescribeClusterNode", "sagemaker:ListClusterNodes", "sagemaker:ListClusters", "eks:DescribeCluster", "eks:AccessKubernetesApi" ], "Resource": "*" } ] } ``` ------ 導覽至 SageMaker HyperPod 主控台中的**儀表板**索引標籤，以安裝 Amazon SageMaker HyperPod 任務治理附加元件。 ------ #### [ Setup using the Amazon EKS AWS CLI ] 使用範例 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/eks/create-addon.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/eks/create-addon.html) EKS AWS CLI 命令，使用 設定 HyperPod 任務控管 Amazon EKS API 和主控台 UI AWS CLI： ``` aws eks create-addon --region region --cluster-name cluster-name --addon-name amazon-sagemaker-hyperpod-taskgovernance ``` ------ 如果安裝成功，您可以在 HyperPod SageMaker AI 主控台中檢視**政策**索引標籤。您也可以使用下列範例 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/eks/describe-addon.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/eks/describe-addon.html) EKS AWS CLI 命令來檢查狀態。 ``` aws eks describe-addon --region region --cluster-name cluster-name --addon-name amazon-sagemaker-hyperpod-taskgovernance ``` # 儀表板 Amazon SageMaker HyperPod 任務治理提供 Amazon EKS 叢集使用率指標的全面儀表板檢視，包括硬體、團隊和任務指標。以下提供 HyperPod EKS 叢集儀表板的相關資訊。 儀表板提供叢集使用率指標的全面檢視，包括硬體、團隊和任務指標。您需要安裝 EKS 附加元件才能檢視儀表板。如需詳細資訊，請參閱[儀表板設定](sagemaker-hyperpod-eks-operate-console-ui-governance-setup-dashboard.md)。 在 [Amazon SageMaker AI 主控台](https://console.aws.amazon.com/sagemaker/)的 **HyperPod 叢集**下，您可以導覽至 HyperPod 主控台，並檢視您區域中的 HyperPod 叢集清單。選擇您的叢集並導覽至**儀表板**索引標籤。儀表板包含下列指標。您可以選擇對應的**匯出**來下載區段的資料。 **使用率** 為關鍵運算資源提供 EKS 時間點和趨勢型指標的運作狀態。根據預設，會顯示**所有執行個體群組**。使用下拉式功能表來篩選執行個體群組。本節中包含的指標如下： + 復原執行個體總數、執行中和待定復原執行個體的數量。待定復原執行個體的數量是指需要注意其復原的執行個體數量。 + GPU、GPU 記憶體、vCPU 和 vCPU 記憶體。 + GPU 使用率、GPU 記憶體使用率、vCPU 使用率和 vCPU 記憶體使用率。 + GPU 和 vCPU 使用率的互動式圖形。 **團隊** 提供團隊特定資源管理的資訊。其中包含： + 執行個體和 GPU 配置。 + GPU 使用率。 + 借用的 GPU 統計資料。 + 任務狀態 (執行中或待定)。 + GPU 使用率與跨團隊運算配置的長條圖檢視。 + 團隊詳細的 GPU 和 vCPU 相關資訊。根據預設，顯示的資訊包含**所有團隊**。您可以選擇下拉式選單，依團隊和執行個體進行篩選。在互動式繪圖中，您可以依時間篩選。 **工作** **注意** 若要在儀表板中檢視 HyperPod EKS 叢集任務： 在指定的 HyperPod 命名空間中為資料科學家使用者設定 Kubernetes 角色型存取控制 (RBAC)，以授權在 Amazon EKS 協調叢集上執行任務。命名空間遵循格式 `hyperpod-ns-team-name`。若要建立 RBAC 許可，請參閱[團隊角色建立指示](https://github.com/aws/sagemaker-hyperpod-cli/tree/main/helm_chart#5-create-team-role)。 確保已使用適當的命名空間和優先順序類別標籤提交您的任務。如需完整範例，請參閱[將任務提交至 SageMaker AI 受管佇列和命名空間](sagemaker-hyperpod-eks-operate-console-ui-governance-cli.md#hp-eks-cli-start-job)。 提供任務相關指標的相關資訊。這包括執行中、待定和先佔的任務數量，以及執行和等待時間統計資料。根據預設，顯示的資訊包含**所有團隊**。您可以選擇下拉式功能表，依團隊進行篩選。在互動式繪圖中，您可以依時間篩選。 # 任務​ 以下提供 Amazon SageMaker HyperPod EKS 叢集任務的相關資訊。任務是傳送至叢集的作業或任務。這些可以是機器學習作業，例如訓練、執行實驗或推論。可檢視的任務詳細資訊清單包括狀態、執行時間，以及每個任務使用的運算量。 在 [Amazon SageMaker AI 主控台](https://console.aws.amazon.com/sagemaker/)的 **HyperPod 叢集**下，您可以導覽至 HyperPod 主控台，並檢視您區域中的 HyperPod 叢集清單。選擇您的叢集並導覽至**任務**索引標籤。 若要讓管理員以外的任何人都能檢視**任務**索引標籤，管理員需要[為 IAM 角色將存取項目新增至 EKS 叢集](https://docs.aws.amazon.com/eks/latest/userguide/access-entries.html)。 **注意** 若要在儀表板中檢視 HyperPod EKS 叢集任務： 在指定的 HyperPod 命名空間中為資料科學家使用者設定 Kubernetes 角色型存取控制 (RBAC)，以授權在 Amazon EKS 協調叢集上執行任務。命名空間遵循格式 `hyperpod-ns-team-name`。若要建立 RBAC 許可，請參閱[團隊角色建立指示](https://github.com/aws/sagemaker-hyperpod-cli/tree/main/helm_chart#5-create-team-role)。 確保已使用適當的命名空間和優先順序類別標籤提交您的任務。如需完整範例，請參閱[將任務提交至 SageMaker AI 受管佇列和命名空間](sagemaker-hyperpod-eks-operate-console-ui-governance-cli.md#hp-eks-cli-start-job)。 對於 EKS 叢集，會顯示 kubeflow (PyTorch、MPI、TensorFlow) 任務。根據預設，會顯示 PyTorch 任務。您可以選擇下拉式功能表或使用搜尋欄位來篩選 PyTorch、MPI、TensorFlow 任務。針對每個任務顯示的資訊包括任務名稱、狀態、命名空間、優先順序類別和建立時間。 # 在 Amazon SageMaker HyperPod 任務治理中使用拓撲感知排程 Amazon SageMaker HyperPod 任務治理中的拓撲感知排程會根據 Amazon EC2 執行個體的實體網路拓撲放置 Pod，以最佳化分散式機器學習工作負載的訓練效率。透過考慮 AWS 基礎設施的階層式結構，包括可用區域、網路區塊和實體機架，拓撲感知排程可確保將需要頻繁通訊的 Pod 排程在近處，以將網路延遲降至最低。這種智慧型配置對於涉及密集 Pod 對 Pod 通訊的大型機器學習訓練任務特別有益，從而減少訓練時間並提高整個叢集的資源使用率。 **注意** 若要使用拓撲感知排程，請確定您的 HyperPod 任務治理版本為 v1.2.2-eksbuild.1 或更高版本。 拓撲感知排程支援下列執行個體類型： + ml.p3dn.24xlarge + ml.p4d.24xlarge + mlp4d.24xlarge + ml.p5.48xlarge + ml.p5e.48xlarge + ml.p5en.48xlarge + ml.p6e-gb200.36xlarge + ml.trn1.2xlarge + ml.trn1.32xlarge + ml.trn1n.32xlarge + ml.trn2.48xlarge + ml.trn2u.48xlarge 拓撲感知排程會與您現有的 HyperPod 工作流程整合，同時透過 kubectl YAML 檔案和 HyperPod CLI 提供靈活的拓撲善好設定。HyperPod 任務治理會自動使用拓撲標籤設定叢集節點，並使用 HyperPod 任務治理政策和資源借用機制，確保拓撲感知排程不會中斷您目前的操作程序。透過對偏好和必要拓撲規格的內建支援，您可以微調工作負載置放，以符合您的特定效能要求，同時在無法滿足拓撲限制條件時，保持回到標準排程的彈性。 透過利用 HyperPod 中的拓撲感知標籤，您可以透過考慮實體網路基礎設施的智慧型 Pod 置放來增強其機器學習工作負載。HyperPod 任務治理會根據階層式資料中心拓撲自動最佳化 Pod 排程，這會直接轉譯為降低網路延遲並改善分散式 ML 任務的訓練效能。這種拓撲感知對於大規模機器學習工作負載特別有價值，因為它透過策略方式將相關的 Pod 放在更接近網路階層的位置，將通訊負荷降至最低。結果是 Pod 之間最佳化的通訊網路延遲、更有效率的資源使用率，以及運算密集型 AI/ML 應用程式更好的整體效能，全都實現，而您不需要手動管理複雜的網路拓撲組態。 以下是 HyperPod 任務治理可在其中排程 Pod 之可用拓撲網路層的標籤： + topology.k8s.aws/network-node-layer-1 + topology.k8s.aws/network-node-layer-2 + topology.k8s.aws/network-node-layer-3 + topology.k8s.aws/ultraserver-id 若要使用拓撲感知排程，請在您的 YAML 檔案中包含下列標籤： + kueue.x-k8s.io/podset-required-topology - 表示此任務必須具有所需的 Pod，且節點中的所有 Pod 必須排程在相同的拓撲層內。 + kueue.x-k8s.io/podset-preferred-topology - 表示此任務必須具有 Pod，但偏好在相同的拓撲層內排程 Pod，但並非必要。HyperPod 任務治理會先嘗試在某層內排程 Pod，然後再嘗試下一個拓撲層。 如果資源未共用相同的拓撲標籤，任務將被暫停。任務將在等待清單中。一旦 Kueue 看到有足夠的資源，就會認可並執行任務。 下列範例示範如何在您的 YAML 檔案中使用標籤： ``` apiVersion: batch/v1 kind: Job metadata: name: test-tas-job namespace: hyperpod-ns-team-name labels: kueue.x-k8s.io/queue-name: hyperpod-ns-team-name-localqueue kueue.x-k8s.io/priority-class: PRIORITY_CLASS-priority spec: parallelism: 10 completions: 10 suspend: true template: metadata: labels: kueue.x-k8s.io/queue-name: hyperpod-ns-team-name-localqueue annotations: kueue.x-k8s.io/podset-required-topology: "topology.k8s.aws/network-node-layer-3" or kueue.x-k8s.io/podset-preferred-topology: "topology.k8s.aws/network-node-layer-3" spec: nodeSelector: topology.k8s.aws/network-node-layer-3: TOPOLOGY_LABEL_VALUE containers: - name: dummy-job image: gcr.io/k8s-staging-perf-tests/sleep:v0.1.0 args: ["3600s"] resources: requests: cpu: "100" restartPolicy: Never ``` 下表說明您可以在 kubectl YAML 檔案中使用的新參數。 | 參數 | Description | | --- | --- | | kueue.x-k8s.io/queue-name | 要用來執行任務的佇列名稱。此 queue-name 的格式必須為 hyperpod-ns-team-name-localqueue。 | | kueue.x-k8s.io/priority-class | 可讓您指定 Pod 排程的優先順序。此規格為選用的。 | | 註釋 | 包含您連接至任務的拓撲註釋。可用的拓撲為 kueue.x-k8s.io/podset-required-topology 和 kueue.x-k8s.io/podset-preferred-topology。您可以使用註釋或 nodeSelector，但不能同時使用這兩者。 | | nodeSelector | 指定代表 Amazon EC2 執行個體置放層的網路層。使用此欄位或註釋，但不能同時使用這兩者。在 YAML 檔案中，您也可以使用 nodeSelector 參數來選擇 Pod 的確切層。若要取得標籤的值，請使用 [DescribeInstanceTopology](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstanceTopology.html) API 操作。 | 您也可以使用 HyperPod CLI 來執行任務，並使用拓撲感知排程。如需 HyperPod CLI 的詳細資訊，請參閱 [SageMaker HyperPod CLI 命令](sagemaker-hyperpod-eks-hyperpod-cli-reference.md)。 ``` hyp create hyp-pytorch-job \ --version 1.1 \ --job-name sample-pytorch-job \ --image 123456789012.dkr.ecr.us-west-2.amazonaws.com/ptjob:latest \ --pull-policy "Always" \ --tasks-per-node 1 \ --max-retry 1 \ --priority high-priority \ --namespace hyperpod-ns-team-name \ --queue-name hyperpod-ns-team-name-localqueue \ --preferred-topology-label topology.k8s.aws/network-node-layer-1 ``` 以下是範例組態檔案，您可以用來搭配拓撲標籤執行 PytorchJob。如果您想要執行 MPI 和 Tensorflow 任務，該檔案大致類似。如果您想要改為執行這些任務，請記得相應地變更組態檔案，例如使用正確的映像而非 PyTorchJob。如果您正在執行 PyTorchJob，則可以將不同的拓撲指派給主節點和工作節點。PyTorchJob 一律有一個主節點，因此我們建議您改用拓撲來支援工作者 Pod。 ``` apiVersion: kubeflow.org/v1 kind: PyTorchJob metadata: annotations: {} labels: kueue.x-k8s.io/queue-name: hyperpod-ns-team-name-localqueue name: tas-test-pytorch-job namespace: hyperpod-ns-team-name spec: pytorchReplicaSpecs: Master: replicas: 1 restartPolicy: OnFailure template: metadata: labels: kueue.x-k8s.io/queue-name: hyperpod-ns-team-name-localqueue spec: containers: - command: - python3 - /opt/pytorch-mnist/mnist.py - --epochs=1 image: docker.io/kubeflowkatib/pytorch-mnist:v1beta1-45c5727 imagePullPolicy: Always name: pytorch Worker: replicas: 10 restartPolicy: OnFailure template: metadata: # annotations: # kueue.x-k8s.io/podset-required-topology: "topology.k8s.aws/network-node-layer-3" labels: kueue.x-k8s.io/queue-name: hyperpod-ns-team-name-localqueue spec: containers: - command: - python3 - /opt/pytorch-mnist/mnist.py - --epochs=1 image: docker.io/kubeflowkatib/pytorch-mnist:v1beta1-45c5727 imagePullPolicy: Always name: pytorch resources: limits: cpu: 1 requests: memory: 200Mi cpu: 1 #nodeSelector: # topology.k8s.aws/network-node-layer-3: xxxxxxxxxxx ``` 若要查看叢集的拓撲，請使用 [DescribeInstanceTopology](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstanceTopology.html) API 操作。根據預設，拓撲會隱藏在 AWS 管理主控台 和 Amazon SageMaker Studio 中。請遵循下列步驟，在您使用的介面中查看它們。 **SageMaker Studio** 1. 在 SageMaker Studio 中，導覽至您的叢集。 1. 在任務檢視中，選擇名稱欄中的選項功能表，然後選擇**管理資料欄**。 1. 選取**請求的拓撲**和**拓撲限制條件**來新增資料欄，以查看 Kubernetes Pod 清單中的拓撲資訊。 **AWS 管理主控台** 1. 開啟 Amazon SageMaker AI 主控台，網址為 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/)。 1. 在 **HyperPod 叢集**下，選擇**叢集管理**。 1. 選擇**任務**索引標籤，然後選擇齒輪圖示。 1. 在執行個體屬性下，切換**請求的拓撲**和**拓撲限制條件**。 1. 選擇**確認**以查看資料表中的拓撲資訊。 # 政策 Amazon SageMaker HyperPod 任務治理可簡化 Amazon EKS 叢集資源的配置方式，以及任務的優先順序。以下提供 HyperPod EKS 叢集政策的相關資訊。如需如何設定任務治理的資訊，請參閱[任務治理設定](sagemaker-hyperpod-eks-operate-console-ui-governance-setup-task-governance.md)。 這些政策分為**運算優先順序**和**運算配置**。以下政策概念將在這些政策的內容中組織。 **運算優先順序**或叢集政策會決定閒置運算的借用方式，以及團隊如何排定任務的優先順序。 + **閒置運算配置**定義閒置運算如何跨團隊配置。亦即，如何從團隊借用未使用的運算。選擇**閒置運算配置**時，您可以選擇下列任一項： + **先到先得**：套用時，團隊彼此不會排定優先順序，而且每個傳入任務都同樣可能取得超額資源。任務會根據提交順序排定優先順序。這表示如果使用者先請求閒置運算，就有可能可以使用 100% 的閒置運算。 + **公平共用**：套用時，團隊會根據其指派的**公平共用權重**借用閒置運算。這些權重是在**運算配置**中定義。如需如何使用此項的詳細資訊，請參閱[共用閒置運算資源範例](#hp-eks-task-governance-policies-examples)。 + **任務優先順序**會定義在運算變成可用時將任務排入佇列的方式。選擇**任務優先順序**時，您可以選擇下列任一項： + **先到先得**：套用時，任務會依請求它們的順序排入佇列。 + **任務排名**：套用時，任務會依其優先順序定義的順序排入佇列。如果選擇此選項，您必須新增優先順序類別以及應排定優先順序的權重。相同優先順序類別的任務將以先到先得的方式執行。在運算配置中啟用時，團隊內優先順序較高的任務會優先取代優先順序較低的任務。 當資料科學家將任務提交至叢集時，他們會使用 YAML 檔案中的優先順序類別名稱。優先順序類別的格式為 `priority-class-name-priority`。如需範例，請參閱 [將任務提交至 SageMaker AI 受管佇列和命名空間](sagemaker-hyperpod-eks-operate-console-ui-governance-cli.md#hp-eks-cli-start-job)。 + **優先順序類別**：這些類別會在借用容量時為任務建立相對優先順序。當任務使用借用的配額執行時，如果傳入任務沒有更多容量可用，則另一個優先順序高於該任務的任務可能會優先取代該任務。如果在**運算配置**中啟用**先佔**，較高優先順序的任務也可能會優先取代其團隊內的任務。 + **未配置的資源共用**可讓團隊借用未透過運算配額配置給任何團隊的運算資源。啟用時，未配置的叢集容量可供團隊自動借用。如需詳細資訊，請參閱[未配置資源共用的運作方式](#sagemaker-hyperpod-eks-operate-console-ui-governance-policies-idle-resource-sharing-how-it-works)。 **運算配置**或運算配額會定義團隊的運算配置，以及提供給團隊哪個權重 (或優先順序層級) 以進行公平共用閒置運算配置。 + **團隊名稱**：團隊名稱。將建立類型為 `hyperpod-ns-team-name` 的對應**命名空間**。 + **成員**：團隊命名空間的成員。您需要為想要成為此團隊一員的資料科學家使用者設定 Kubernetes 角色型存取控制 (RBAC)，才能在與 Amazon EKS 協作的 HyperPod 叢集上執行任務。若要設定 Kubernetes RBAC，請使用[建立團隊角色](https://github.com/aws/sagemaker-hyperpod-cli/tree/main/helm_chart#5-create-team-role)中的指示。 + **公平共用權重**：這是套用**公平共用**進行**閒置運算配置**時指派給團隊的優先順序層級。最高優先順序的權重為 100，最低優先順序的權重為 0。較高的權重可讓團隊更快存取共用容量內未使用的資源。零權重表示優先順序最低，這意味著與其他團隊相比，此團隊總是處於劣勢。 公平共用權重會在此團隊與其他團隊爭奪可用資源時為其提供比較優勢。許可會優先從權重最高且借用最低的團隊排程任務。例如，如果團隊 A 的權重為 10，而團隊 B 的權重為 5，則團隊 A 會優先存取未使用的資源，因為其中的任務排程早於團隊 B。 + **任務先佔**：根據優先順序從任務接管運算。根據預設，租用閒置運算的團隊會優先取代來自其他團隊的任務。 + **借出和借用**：團隊如何借出閒置運算，以及團隊是否可以向其他團隊借用。 + 以**百分比為基礎的借用限制**：允許團隊借用的閒置運算限制，以其保證配額的百分比表示。團隊最多可借用 10，000% 的已配置運算。您在此處提供的值會解譯為百分比。例如，500 的值將解譯為 500%。此百分比可均勻套用至團隊配額中的所有資源類型 (CPU、GPU、記憶體） 和執行個體類型。 + **絕對借用限制**：允許團隊借用的閒置運算限制，定義為每個執行個體類型的絕對資源值。這可讓您精細控制特定執行個體類型的借用行為。您需要使用與**運算配額**相同的結構描述來指定絕對限制，包括執行個體計數、加速器、vCPU、記憶體或加速器分割區。您可以為團隊配額中的一或多個執行個體類型指定絕對限制。 如需如何使用這些概念的資訊，例如優先順序類別和命名空間，請參閱[HyperPod 任務控管 AWS CLI 命令範例](sagemaker-hyperpod-eks-operate-console-ui-governance-cli.md)。 ## 共用閒置運算資源範例 總預留配額不應超過叢集對該資源的可用容量，以確保適當的配額管理。例如，如果叢集包含 20 個 `ml.c5.2xlarge` 執行個體，則指派給團隊的累積配額應保持在 20 以下。 如果團隊的**運算配置**政策允許**借出和借用**或**借出**，則閒置容量會由這些團隊之間共用。例如，團隊 A 和團隊 B 已啟用**借出和借用**。團隊 A 的配額為 6，但其任務只使用 2，而團隊 B 的配額為 5，其任務使用 4。提交給團隊 B 的任務需要 4 個資源。3 個將從團隊 A 借用。 如果任何團隊的**運算配置**政策設定為**不借出**，則團隊將無法借用超出自己配置的任何額外容量。 ## 未配置資源共用的運作方式 未配置的資源共用會自動管理未配置給叢集中任何運算配額的資源集區。這表示 HyperPod 會持續監控叢集狀態，並隨著時間自動更新至正確的組態。 **初始設定** + 當您在 ClusterSchedulerConfig `Enabled`中`IdleResourceSharing`將 設定為 （預設為 `Disabled`) 時，HyperPod 任務控管會開始監控叢集，並透過從總節點容量減去團隊配額來計算可用的閒置資源。 + 建立未配置的資源共用 ClusterQueues以代表可借用的資源集區。 + 當您第一次啟用未配置的資源共用時，基礎設施設定需要幾分鐘的時間。您可以透過政策和 ClusterSchedulerConfig `Status``DetailedStatus`監控進度。 **持續對帳** + HyperPod 任務控管會持續監控節點新增或移除以及叢集佇列配額更新等變更。 + 發生變更時，未配置的資源共用會重新計算配額並更新 ClusterQueues。調校通常會在幾秒鐘內完成。 **監控** 您可以檢查未配置的資源共用 ClusterQueues，以確認未配置的資源共用已完全設定： ``` kubectl get clusterqueue | grep hyperpod-ns-idle-resource-sharing ``` 當您看到名稱如 的 ClusterQueues 時`hyperpod-ns-idle-resource-sharing-cq-1`，未配置的資源共用會處於作用中狀態。請注意，視叢集中的資源樣式而定，可能會有多個未配置的資源共用 ClusterQueues。 ## 未配置資源共用的節點資格 未配置的資源共用僅包含符合下列要求的節點： 1. **節點就緒狀態** + 節點必須處於 `Ready` 狀態，才能對未配置的資源集區做出貢獻。 + 容量計算會排除處於 `NotReady`或其他未就緒狀態的節點。 + 當節點變成 時`Ready`，它會自動包含在下一個調校週期中。 1. **節點可排程狀態** + 具有 的節點`spec.unschedulable: true`會從未配置的資源共用中排除。 + 當節點再次變成可排程時，它會自動包含在下一個調校週期中。 1. **MIG 組態 （僅限 GPU 節點）** + 對於具有 MIG （多執行個體 GPU) 分割`success`的 GPU 節點，`nvidia.com/mig.config.state`標籤必須顯示為節點提供 MIG 設定檔給未配置的資源共用。 + 一旦 MIG 組態成功完成，這些節點就會自動重試。 1. **支援的執行個體類型** + 執行個體必須是支援的 SageMaker HyperPod 執行個體類型。 + 請參閱 SageMaker HyperPod 叢集中支援的執行個體類型清單。 **Topics** + [共用閒置運算資源範例](#hp-eks-task-governance-policies-examples) + [未配置資源共用的運作方式](#sagemaker-hyperpod-eks-operate-console-ui-governance-policies-idle-resource-sharing-how-it-works) + [未配置資源共用的節點資格](#sagemaker-hyperpod-eks-operate-console-ui-governance-policies-idle-resource-sharing-node-eligibility) + [建立政策](sagemaker-hyperpod-eks-operate-console-ui-governance-policies-create.md) + [編輯政策](sagemaker-hyperpod-eks-operate-console-ui-governance-policies-edit.md) + [刪除政策](sagemaker-hyperpod-eks-operate-console-ui-governance-policies-delete.md) + [在 Amazon SageMaker HyperPod 任務治理中配置運算配額](sagemaker-hyperpod-eks-operate-console-ui-governance-policies-compute-allocation.md) # 建立政策 您可以在**政策**索引標籤中建立**叢集政策**和**運算配置**組態。以下提供如何建立下列組態的指示。 + 建立**叢集政策**以更新任務的優先順序排定方式和閒置運算的配置方式。 + 建立**運算配置**，為團隊建立新的運算配置政策。 **注意** 建立**運算配置**時，您需要為對應命名空間中的資料科學家使用者設定 Kubernetes 角色型存取控制 (RBAC)，以在與 Amazon EKS 協調的 HyperPod 叢集上執行任務。命名空間具有格式 `hyperpod-ns-team-name`。若要設定 Kubernetes RBAC，請使用[建立團隊角色](https://github.com/aws/sagemaker-hyperpod-cli/tree/main/helm_chart#5-create-team-role)中的指示。 如需 HyperPod 任務治理 EKS 叢集政策概念的相關資訊，請參閱[政策](sagemaker-hyperpod-eks-operate-console-ui-governance-policies.md)。 **建立 HyperPod 任務治理政策** 此程序假設您已建立一個使用 HyperPod 設定的 Amazon EKS 叢集。如果您尚未這麼做，則請參閱[使用 Amazon EKS 協同運作建立 SageMaker HyperPod 叢集](sagemaker-hyperpod-eks-operate-console-ui-create-cluster.md)。 1. 導覽至 [Amazon SageMaker AI 主控台](https://console.aws.amazon.com/sagemaker/)。 1. 在左側導覽窗格的 **HyperPod 叢集**下，選擇**叢集管理**。 1. 選擇 **SageMaker HyperPod 叢集**下列出的 Amazon EKS 叢集。 1. 選擇 **Policies (政策)** 標籤。 1. 若要建立您的**叢集政策**： 1. 選擇對應的**編輯**，以更新任務的優先順序和閒置運算的配置方式。 1. 完成變更後，請選擇**提交**。 1. 若要建立**運算配置**： 1. 1. 選擇對應的**建立**。這會帶您前往運算配置建立頁面。 1. 完成變更後，請選擇**提交**。 # 編輯政策 您可以在**政策**索引標籤中編輯**叢集政策**和**運算配置**組態。以下提供如何編輯下列組態的指示。 + 編輯**叢集政策**以更新任務的優先順序排定方式和閒置運算的配置方式。 + 編輯**運算配置**，為團隊建立新的運算配置政策。 **注意** 建立**運算配置**時，您需要為對應命名空間中的資料科學家使用者設定 Kubernetes 角色型存取控制 (RBAC)，以在與 Amazon EKS 協調的 HyperPod 叢集上執行任務。命名空間具有格式 `hyperpod-ns-team-name`。若要設定 Kubernetes RBAC，請使用[建立團隊角色](https://github.com/aws/sagemaker-hyperpod-cli/tree/main/helm_chart#5-create-team-role)中的指示。 如需 HyperPod 任務治理 EKS 叢集政策概念的詳細資訊，請參閱 [政策](sagemaker-hyperpod-eks-operate-console-ui-governance-policies.md)。 **編輯 HyperPod 任務治理政策** 此程序假設您已建立一個使用 HyperPod 設定的 Amazon EKS 叢集。如果您尚未這麼做，則請參閱[使用 Amazon EKS 協同運作建立 SageMaker HyperPod 叢集](sagemaker-hyperpod-eks-operate-console-ui-create-cluster.md)。 1. 導覽至 [Amazon SageMaker AI 主控台](https://console.aws.amazon.com/sagemaker/)。 1. 在左側導覽窗格的 **HyperPod 叢集**下，選擇**叢集管理**。 1. 選擇 **SageMaker HyperPod 叢集**下列出的 Amazon EKS 叢集。 1. 選擇 **Policies (政策)** 標籤。 1. 若要編輯您的**叢集政策**： 1. 選擇對應的**編輯**，以更新任務的優先順序和閒置運算的配置方式。 1. 完成變更後，請選擇**提交**。 1. 若要編輯您的**運算配置**： 1. 1. 在**運算配置**下選擇您要編輯的組態。這會將您前往容器組態詳細資訊頁面。 1. 如果您想要編輯這些組態，請選擇**編輯**。 1. 完成變更後，請選擇**提交**。 # 刪除政策 您可以使用 SageMaker AI 主控台或 AWS CLI刪除**叢集政策**和**運算配置**組態。下頁提供如何刪除 SageMaker HyperPod 任務治理政策和組態的指示。 如需 HyperPod 任務治理 EKS 叢集政策概念的詳細資訊，請參閱 [政策](sagemaker-hyperpod-eks-operate-console-ui-governance-policies.md)。 **注意** 如果您有列出或刪除任務治理政策方面的問題，您可能需要更新叢集管理員的最低許可集。請參閱 [叢集管理員的 IAM 使用者](sagemaker-hyperpod-prerequisites-iam.md#sagemaker-hyperpod-prerequisites-iam-cluster-admin) 區段中的 **Amazon EKS** 索引標籤。如需其他資訊，請參閱 [刪除叢集](sagemaker-hyperpod-eks-operate-console-ui-governance-troubleshoot.md#hp-eks-troubleshoot-delete-policies)。 ## 刪除 HyperPod 任務治理政策 (主控台) 以下使用 SageMaker AI 主控台來刪除您的 HyperPod 任務治理政策。 **注意** 您無法使用 SageMaker AI 主控台刪除**叢集政策** (`ClusterSchedulerConfig`)。若要了解如何使用 執行此操作 AWS CLI，請參閱 [刪除 HyperPod 任務治理政策 (AWS CLI)](#sagemaker-hyperpod-eks-operate-console-ui-governance-policies-delete-cli)。 **刪除任務治理政策 (主控台)** 1. 導覽至 [Amazon SageMaker AI 主控台](https://console.aws.amazon.com/sagemaker/)。 1. 在左側導覽窗格的 **HyperPod 叢集**下，選擇**叢集管理**。 1. 選擇 **SageMaker HyperPod 叢集**下列出的 Amazon EKS 叢集。 1. 選擇 **Policies (政策)** 標籤。 1. 若要刪除您的**運算配置** (`ComputeQuota`)： 1. 在**運算配置**區段中，選取您要刪除的組態。 1. 從**動作**下拉式功能表中，選擇**刪除**。 1. 遵循 UI 中的指示完成任務。 ## 刪除 HyperPod 任務治理政策 (AWS CLI) 以下使用 AWS CLI 刪除您的 HyperPod 任務控管政策。 **注意** 如果您在使用下列命令時遇到問題，您可能需要更新您的 AWS CLI。如需詳細資訊，請參閱[安裝或更新至最新版本的 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。 **刪除任務治理政策 (AWS CLI)** 首先為後續的 AWS CLI 命令設定變數。 ``` REGION=aws-region ``` 1. 取得與您要刪除之政策相關聯的 *cluster-arn*。您可以使用下列 AWS CLI 命令來列出 中的叢集 AWS 區域。 ``` aws sagemaker list-clusters \ --region ${REGION} ``` 1. 若要刪除您的運算配置 (`ComputeQuota`)： 1. 列出與 HyperPod 叢集相關聯的所有運算配額。 ``` aws sagemaker list-compute-quotas \ --cluster-arn cluster-arn \ --region ${REGION} ``` 1. 對於您要刪除的每個 `compute-quota-id`，請執行下列命令來刪除運算配額。 ``` aws sagemaker delete-compute-quota \ --compute-quota-id compute-quota-id \ --region ${REGION} ``` 1. 若要刪除您的叢集政策 (`ClusterSchedulerConfig`)： 1. 列出與 HyperPod 叢集相關聯的所有叢集政策。 ``` aws sagemaker list-cluster-scheduler-configs \ --cluster-arn cluster-arn \ --region ${REGION} ``` 1. 對於您要刪除的每個 `cluster-scheduler-config-id`，請執行下列命令來刪除運算配額。 ``` aws sagemaker delete-cluster-scheduler-config --cluster-scheduler-config-id scheduler-config-id \ --region ${REGION} ``` # 在 Amazon SageMaker HyperPod 任務治理中配置運算配額 叢集管理員可以決定組織如何使用購買的運算。這樣做可減少浪費和閒置資源。您可以配置運算配額，讓團隊可以彼此借用未使用的資源。HyperPod 任務治理中的運算配額配置可讓管理員在執行個體層級和更精細的資源層級配置資源。此功能允許精細控制個別運算資源，而不是要求整個執行個體配置，為團隊提供靈活且有效率的資源管理。在精細層級配置可消除傳統執行個體層級配置的效率低下情況。透過此方法，您可以最佳化資源使用率並減少閒置運算。 運算配額配置支援三種類型的資源配置：加速器、vCPU 和記憶體。加速器是加速電腦執行個體中執行函數的元件，例如浮點數計算、圖形處理或資料模式比對。加速器包括 GPU、 Trainium 加速器和神經元核心。對於多團隊 GPU 共用，不同的團隊可以從相同的執行個體類型接收特定的 GPU 配置，最大限度地提高加速器硬體的使用率。對於需要額外 RAM 進行資料預先處理或模型快取案例的記憶體密集型工作負載，您可以配置超出預設 GPU 與記镱體比率的記憶體配額。對於需要大量 CPU 資源以及 GPU 訓練的 CPU 密集型預先處理任務，您可以配置獨立的 CPU 資源配置。 一旦您提供值，HyperPod 任務治理就會使用公式**配置的資源除以執行個體中可用的資源總數**來計算比率。然後，HyperPod 任務治理會使用此比率，將預設配置套用至其他資源，但您可以覆寫這些預設值，並根據使用案例自訂它們。以下是 HyperPod 任務治理如何根據您的值配置資源的範例案例： + **僅指定加速器** - HyperPod 任務治理會根據加速器值，將預設比率套用至 vCPU 和記憶體。 + **僅指定 vCPU** - HyperPod 任務治理會計算比率並將其套用至記憶體。加速器設定為 0。 + **僅指定記憶體** - HyperPod 任務治理會計算比率並將其套用至 vCPU，因為執行記憶體指定的工作負載需要運算。加速器設定為 0。 若要以程式設計方式控制配額配置，您可以使用 [ComputeQuotaResourceConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ComputeQuotaResourceConfig.html) 物件，並以整數指定配置。 ``` { "ComputeQuotaConfig": { "ComputeQuotaResources": [{ "InstanceType": "ml.g5.24xlarge", "Accelerators": "16", "vCpu": "200.0", "MemoryInGiB": "2.0" }] } } ``` 若要查看所有配置，包括預設值，請使用 [DescribeComputeQuota](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeComputeQuota.html) 操作。若要更新您的配置，請使用 [UpdateComputeQuota](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateComputeQuota.html) 操作。 您也可以使用 HyperPod CLI 來配置運算配額。如需 HyperPod CLI 的詳細資訊，請參閱 [在 Amazon EKS 協作的 SageMaker HyperPod 叢集上執行任務](sagemaker-hyperpod-eks-run-jobs.md)。下列範例示範如何使用 HyperPod CLI 設定運算配額。 ``` hyp create hyp-pytorch-job --version 1.1 --job-name sample-job \ --image 123456789012.dkr.ecr.us-west-2.amazonaws.com/ptjob:latest \ --pull-policy "Always" \ --tasks-per-node 1 \ --max-retry 1 \ --priority high-priority \ --namespace hyperpod-ns-team-name \ --queue-name hyperpod-ns-team-name-localqueue \ --instance-type sample-instance-type \ --accelerators 1 \ --vcpu 3 \ --memory 1 \ --accelerators-limit 1 \ --vcpu-limit 4 \ --memory-limit 2 ``` 若要使用 AWS 主控台配置配額，請遵循下列步驟。 1. 開啟 Amazon SageMaker AI 主控台，網址為 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/)。 1. 在 HyperPod 叢集下，選擇**叢集管理**。 1. 在**運算配置**下，選擇**建立**。 1. 如果您還沒有執行個體，請選擇**新增配置**以新增執行個體。 1. 在**配置**下，選擇依執行個體或個別資源配置。如果您依個別資源配置，SageMaker AI 會根據您選擇的比率自動將配置指派給其他資源。若要覆寫此比率型配置，請使用對應的切換來覆寫該運算。 1. 重複步驟 4 和 5 來設定額外的執行個體。 配置運算配額後，您可以接著透過 HyperPod CLI 或 `kubectl` 提交任務。HyperPod 會根據可用的配額有效率地排程工作負載。 # 配置 GPU 分割區配額 您可以擴展運算配額分配以支援 GPU 分割，在 GPU 分割區層級實現精細的資源共享。在叢集中支援的 GPUs 上啟用 GPU 分割時，每個實體 GPU 都可以分割成多個隔離的 GPUs，其中包含定義的運算、記憶體和串流多處理器配置。如需 GPU 分割的詳細資訊，請參閱 [在 Amazon SageMaker HyperPod 中使用 GPU 分割區](sagemaker-hyperpod-eks-gpu-partitioning.md)。您可以將特定 GPU 分割區配置給團隊，讓多個團隊共用單一 GPU，同時維持硬體層級隔離和可預測的效能。 例如，具有 8 個 H100 GPUs 的 ml.p5.48xlarge 執行個體可以分割成 GPU 分割區，而且您可以根據其任務需求將個別分割區配置給不同的團隊。當您指定 GPU 分割區配置時，HyperPod 任務控管會根據 GPU 分割區計算比例 vCPU 和記憶體配額，類似於 GPU 層級配置。此方法可消除閒置容量，並在同一實體 GPU 上跨多個並行任務啟用具成本效益的資源共用，藉此最大化 GPU 使用率。 ## 建立運算配額 ``` aws sagemaker create-compute-quota \ --name "fractional-gpu-quota" \ --compute-quota-config '{ "ComputeQuotaResources": [ { "InstanceType": "ml.p4d.24xlarge", "AcceleratorPartition": { "Count": 4, "Type": "mig-1g.5gb" } } ], "ResourceSharingConfig": { "Strategy": "LendAndBorrow", "BorrowLimit": 100 } }' ``` ## 驗證配額資源 ``` # Check ClusterQueue kubectl get clusterqueues kubectl describe clusterqueue QUEUE_NAME # Check ResourceFlavors kubectl get resourceflavor kubectl describe resourceflavor FLAVOR_NAME ``` # HyperPod 任務控管 AWS CLI 命令範例 您可以透過 Kubectl 或透過 HyperPod 自訂 CLI 來使用 HyperPod 搭配 EKS。您可以透過 Studio 或 使用這些命令 AWS CLI。以下提供 SageMaker HyperPod 任務控管範例，說明如何使用 HyperPod AWS CLI 命令檢視叢集詳細資訊。如需詳細資訊，包括如何安裝，請參閱 [HyperPod CLI Github 儲存庫](https://github.com/aws/sagemaker-hyperpod-cli)。 **Topics** + [取得叢集加速器裝置配額資訊](#hp-eks-cli-get-clusters) + [將任務提交至 SageMaker AI 受管佇列和命名空間](#hp-eks-cli-start-job) + [列出任務](#hp-eks-cli-list-jobs) + [取得任務詳細資訊](#hp-eks-cli-get-job) + [暫停和取消暫停任務](#hp-eks-cli-patch-job) + [偵錯任務](#hp-eks-cli-other) ## 取得叢集加速器裝置配額資訊 下列範例命令會取得叢集加速器裝置配額的相關資訊。 ``` hyperpod get-clusters -n hyperpod-ns-test-team ``` 此範例 `hyperpod-ns-test-team` 中的命名空間是在運算配置建立時根據所提供的團隊名稱 `test-team` 建立於 Kubernetes。如需詳細資訊，請參閱[編輯政策](sagemaker-hyperpod-eks-operate-console-ui-governance-policies-edit.md)。 回應範例： ``` [ { "Cluster": "hyperpod-eks-test-cluster-id", "InstanceType": "ml.g5.xlarge", "TotalNodes": 2, "AcceleratorDevicesAvailable": 1, "NodeHealthStatus=Schedulable": 2, "DeepHealthCheckStatus=Passed": "N/A", "Namespaces": { "hyperpod-ns-test-team": { "TotalAcceleratorDevices": 1, "AvailableAcceleratorDevices": 1 } } } ] ``` ## 將任務提交至 SageMaker AI 受管佇列和命名空間 下列範例命令會將任務提交至您的 HyperPod 叢集。如果您只能存取一個團隊，在這種情況下，HyperPod AWS CLI 會自動為您指派佇列。否則，如果發現多個佇列，我們將顯示所有可行的選項供您選取。 ``` hyperpod start-job --job-name hyperpod-cli-test --job-kind kubeflow/PyTorchJob --image docker.io/kubeflowkatib/pytorch-mnist-cpu:v1beta1-bc09cfd --entry-script /opt/pytorch-mnist/mnist.py --pull-policy IfNotPresent --instance-type ml.g5.xlarge --node-count 1 --tasks-per-node 1 --results-dir ./result --priority training-priority ``` 優先順序類別是在**叢集政策**中定義，其會定義任務的優先順序排定方式和閒置運算的配置方式。當資料科學家提交任務時，他們會使用格式為 `priority-class-name-priority` 的其中一個優先順序類別名稱。在此範例中，`training-priority` 是指名為 “training” 的優先順序類別。如需政策的詳細資訊，請參閱[政策](sagemaker-hyperpod-eks-operate-console-ui-governance-policies.md)。 如果未指定優先順序類別，任務會被視為低優先順序任務，任務排名值為 0。 如果指定了優先順序類別，但未對應至**叢集政策**中定義的其中一個優先順序類別，則提交會失敗，且錯誤訊息會提供一組定義的優先順序類別。 您也可以使用下列命令，提交使用 YAML 組態檔案的任務： ``` hyperpod start-job --config-file ./yaml-configuration-file-name.yaml ``` 以下是 YAML 組態檔案範例，等同於上述提交任務。 ``` defaults: - override hydra/job_logging: stdout hydra: run: dir: . output_subdir: null training_cfg: entry_script: /opt/pytorch-mnist/mnist.py script_args: [] run: name: hyperpod-cli-test nodes: 1 ntasks_per_node: 1 cluster: cluster_type: k8s instance_type: ml.g5.xlarge custom_labels: kueue.x-k8s.io/priority-class: training-priority cluster_config: label_selector: required: sagemaker.amazonaws.com/node-health-status: - Schedulable preferred: sagemaker.amazonaws.com/deep-health-check-status: - Passed weights: - 100 pullPolicy: IfNotPresent base_results_dir: ./result container: docker.io/kubeflowkatib/pytorch-mnist-cpu:v1beta1-bc09cfd env_vars: NCCL_DEBUG: INFO ``` 或者，您可以使用 `kubectl` 提交任務，以確保任務出現在**儀表板**索引標籤中。下列是範例 kubectl 命令。 ``` kubectl apply -f ./yaml-configuration-file-name.yaml ``` 提交任務時，請包含您的佇列名稱和優先順序類別標籤。例如，搭配佇列名稱 `hyperpod-ns-team-name-localqueue` 和優先順序類別 `priority-class-name-priority`，您必須包含下列標籤： + `kueue.x-k8s.io/queue-name: hyperpod-ns-team-name-localqueue` + `kueue.x-k8s.io/priority-class: priority-class-name-priority` 下列 YAML 組態程式碼片段示範如何將標籤新增至您的原始組態檔案，以確保您的任務出現在**儀表板**索引標籤中： ``` metadata: name: job-name namespace: hyperpod-ns-team-name labels: kueue.x-k8s.io/queue-name: hyperpod-ns-team-name-localqueue kueue.x-k8s.io/priority-class: priority-class-name-priority ``` ## 列出任務 下列命令會列出任務及其詳細資訊。 ``` hyperpod list-jobs ``` 回應範例： ``` { "jobs": [ { "Name": "hyperpod-cli-test", "Namespace": "hyperpod-ns-test-team", "CreationTime": "2024-11-18T21:21:15Z", "Priority": "training", "State": "Succeeded" } ] } ``` ## 取得任務詳細資訊 下列命令提供任務的詳細資訊。如果未指定命名空間，HyperPod AWS CLI 會擷取您能夠存取的 SageMaker AI 管理的命名空間。 ``` hyperpod get-job --job-name hyperpod-cli-test ``` 回應範例： ``` { "Name": "hyperpod-cli-test", "Namespace": "hyperpod-ns-test-team", "Label": { "app": "hyperpod-cli-test", "app.kubernetes.io/managed-by": "Helm", "kueue.x-k8s.io/priority-class": "training" }, "CreationTimestamp": "2024-11-18T21:21:15Z", "Status": { "completionTime": "2024-11-18T21:25:24Z", "conditions": [ { "lastTransitionTime": "2024-11-18T21:21:15Z", "lastUpdateTime": "2024-11-18T21:21:15Z", "message": "PyTorchJob hyperpod-cli-test is created.", "reason": "PyTorchJobCreated", "status": "True", "type": "Created" }, { "lastTransitionTime": "2024-11-18T21:21:17Z", "lastUpdateTime": "2024-11-18T21:21:17Z", "message": "PyTorchJob hyperpod-ns-test-team/hyperpod-cli-test is running.", "reason": "PyTorchJobRunning", "status": "False", "type": "Running" }, { "lastTransitionTime": "2024-11-18T21:25:24Z", "lastUpdateTime": "2024-11-18T21:25:24Z", "message": "PyTorchJob hyperpod-ns-test-team/hyperpod-cli-test successfully completed.", "reason": "PyTorchJobSucceeded", "status": "True", "type": "Succeeded" } ], "replicaStatuses": { "Worker": { "selector": "training.kubeflow.org/job-name=hyperpod-cli-test,training.kubeflow.org/operator-name=pytorchjob-controller,training.kubeflow.org/replica-type=worker", "succeeded": 1 } }, "startTime": "2024-11-18T21:21:15Z" }, "ConsoleURL": "https://us-west-2.console.aws.amazon.com/sagemaker/home?region=us-west-2#/cluster-management/hyperpod-eks-test-cluster-id“ } ``` ## 暫停和取消暫停任務 如果您想要從排程器移除一些已提交的任務，HyperPod AWS CLI 會提供 `suspend` 命令來暫時從協同運作中移除任務。除非透過 `unsuspend` 命令手動取消暫停任務，否則不會再排程已暫停的任務 若要暫停任務： ``` hyperpod patch-job suspend --job-name hyperpod-cli-test ``` 若要將任務新增回佇列： ``` hyperpod patch-job unsuspend --job-name hyperpod-cli-test ``` ## 偵錯任務 HyperPod AWS CLI 也提供其他命令，讓您偵錯任務提交問題。例如，HyperPod AWS CLI Github 儲存庫`get-logs`中的 `list-pods`和 。 # 疑難排解 以下頁面包含針對 HyperPod EKS 叢集進行疑難排解的已知解決方案。 **Topics** + [儀表板索引標籤](#hp-eks-troubleshoot-dashboard) + [任務索引標籤](#hp-eks-troubleshoot-tasks) + [政策](#hp-eks-troubleshoot-policies) + [刪除叢集](#hp-eks-troubleshoot-delete-policies) + [未配置的資源共用](#hp-eks-troubleshoot-unallocated-resource-sharing) ## 儀表板索引標籤 **無法安裝 EKS 附加元件** 若要讓 EKS 附加元件安裝成功，您將需要 Kubernets 版本 >= 1.30。若要更新，請參閱[更新 Kubernetes 版本](https://docs.aws.amazon.com/eks/latest/userguide/update-cluster.html)。 若要讓 EKS 附加元件安裝成功，所有節點都必須處於**備妥**狀態，且所有 Pod 都必須處於**執行中**狀態。 若要檢查節點的狀態，請使用 [https://docs.aws.amazon.com/cli/latest/reference/sagemaker/list-cluster-nodes.html](https://docs.aws.amazon.com/cli/latest/reference/sagemaker/list-cluster-nodes.html) AWS CLI 命令或導覽至 EKS [主控台中的 EKS](https://console.aws.amazon.com/eks/home#/clusters) 叢集，並檢視節點的狀態。解決每個節點的問題，或聯絡您的管理員。如果節點狀態為**不明**，請刪除節點。一旦所有節點狀態都是**備妥**，請從 [Amazon SageMaker AI 主控台](https://console.aws.amazon.com/sagemaker/)重試在 HyperPod 中安裝 EKS 附加元件。 若要檢查 Pod 的狀態，請使用 [Kubernetes CLI](https://kubernetes.io/docs/reference/kubectl/) 命令 `kubectl get pods -n cloudwatch-agent`，或在 [EKS 主控台](https://console.aws.amazon.com/eks/home#/clusters)中導覽至您的 EKS 叢集，並使用命名空間 `cloudwatch-agent` 檢視 Pod 的狀態。解決 Pod 的問題，或聯絡您的管理員以解決問題。一旦所有 Pod 狀態都是**執行中**，請從 [Amazon SageMaker AI 主控台](https://console.aws.amazon.com/sagemaker/)重試在 HyperPod 中安裝 EKS 附加元件。 如需更多疑難排解，請參閱[針對 Amazon CloudWatch 可觀測性 EKS 附加元件進行疑難排解](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html#Container-Insights-setup-EKS-addon-troubleshoot)。 ## 任務索引標籤 如果您看到有關為何**未在叢集上設定自訂資源定義 (CRD)** 的錯誤訊息，請將 `EKSAdminViewPolicy` 和 `ClusterAccessRole` 政策授予您的網域執行角色。 + 如需有關如何取得執行角色的資訊，請參閱[取得您的執行角色](sagemaker-roles.md#sagemaker-roles-get-execution-role)。 + 若要了解如何將政策附加至 IAM 使用者或群組，請參閱[新增和移除 IAM 身分許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。 ## 政策 以下列出了使用 HyperPod API 或主控台解決政策相關錯誤的解決方案。 + 如果政策處於 `CreateFailed` 或 `CreateRollbackFailed` 狀態，您需要刪除失敗的政策並建立新的政策。 + 如果政策處於 `UpdateFailed` 狀態，請使用相同的政策 ARN 重試更新。 + 如果政策處於 `UpdateRollbackFailed` 狀態，您需要刪除失敗的政策，然後建立新的政策。 + 如果政策處於 `DeleteFailed` 或 `DeleteRollbackFailed` 狀態，請使用相同的政策 ARN 重試刪除。 + 如果您在嘗試使用 HyperPod 主控台刪除**運算優先順序**或叢集政策時遇到錯誤，請使用 API 刪除 `cluster-scheduler-config`。若要檢查資源的狀態，請前往運算配置的詳細資訊頁面。 若要查看失敗的詳細資訊，請使用 describe API。 ## 刪除叢集 下列列出與刪除叢集相關的錯誤的已知解決方案。 + 當叢集刪除由於連接的 SageMaker HyperPod 任務治理政策而失敗時，您將需要 [刪除政策](sagemaker-hyperpod-eks-operate-console-ui-governance-policies-delete.md)。 + 當叢集刪除由於缺少下列許可而失敗時，您將需要更新您的叢集管理員最低許可集。請參閱 [叢集管理員的 IAM 使用者](sagemaker-hyperpod-prerequisites-iam.md#sagemaker-hyperpod-prerequisites-iam-cluster-admin) 區段中的 **Amazon EKS** 索引標籤。 + `sagemaker:ListComputeQuotas` + `sagemaker:ListClusterSchedulerConfig` + `sagemaker:DeleteComputeQuota` + `sagemaker:DeleteClusterSchedulerConfig` ## 未配置的資源共用 如果您未配置的資源集區容量低於預期： 1. **檢查節點就緒狀態** ``` kubectl get nodes ``` 驗證所有節點是否在 STATUS 欄中顯示`Ready`狀態。 1. **檢查節點可排程狀態** ``` kubectl get nodes -o custom-columns=NAME:.metadata.name,UNSCHEDULABLE:.spec.unschedulable ``` 驗證節點是否顯示 ``或 `false`（而非 `true`)。 1. **列出未配置的資源共用 ClusterQueues：** ``` kubectl get clusterqueue | grep hyperpod-ns-idle-resource-sharing ``` 這會顯示所有未配置的資源共用 ClusterQueues 如果 ClusterQueues 未顯示，請檢查 ClusterSchedulerConfig 政策`FailureReason`下的 ，以查看是否有任何失敗訊息以繼續偵錯。 1. **驗證未配置的資源共用配額：** ``` kubectl describe clusterqueue hyperpod-ns-idle-resource-sharing- ``` 檢查 `spec.resourceGroups[].flavors[].resources`區段以查看為每個資源口味配置的配額。 視叢集中的資源樣式而定，可能會有多個未配置的資源共用 ClusterQueues。 1. **檢查 MIG 組態狀態 (GPU 節點）：** ``` kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels.nvidia\.com/mig\.config\.state}{"\n"}{end}' ``` 驗證啟用 MIG 的節點會顯示`success`狀態。 # Amazon SageMaker HyperPod 任務治理的歸因文件 在下文中，您可以了解 Amazon SageMaker HyperPod 任務治理中所使用資料的歸因和第三方授權。 **Topics** + [[base-files](https://packages.debian.org/bookworm/base-files)](#hp-eks-task-governance-attributions-base-files) + [[netbase](https://packages.debian.org/source/stable/netbase)](#hp-eks-task-governance-attributions-netbase) + [[golang-lru](https://github.com/hashicorp/golang-lru)](#hp-eks-task-governance-attributions-golang-lru) ## [base-files](https://packages.debian.org/bookworm/base-files) ``` This is the Debian prepackaged version of the Debian Base System Miscellaneous files. These files were written by Ian Murdock and Bruce Perens . This package was first put together by Bruce Perens , from his own sources. The GNU Public Licenses in /usr/share/common-licenses were taken from ftp.gnu.org and are copyrighted by the Free Software Foundation, Inc. The Artistic License in /usr/share/common-licenses is the one coming from Perl and its SPDX name is "Artistic License 1.0 (Perl)". Copyright © 1995-2011 Software in the Public Interest. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. On Debian systems, the complete text of the GNU General Public License can be found in `/usr/share/common-licenses/GPL'. ``` ## [netbase](https://packages.debian.org/source/stable/netbase) ``` Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Comment: This package was created by Peter Tobias tobias@et-inf.fho-emden.de on Wed, 24 Aug 1994 21:33:28 +0200 and maintained by Anthony Towns until 2001. It is currently maintained by Marco d'Itri . Files: * Copyright: Copyright © 1994-1998 Peter Tobias Copyright © 1998-2001 Anthony Towns Copyright © 2002-2022 Marco d'Itri License: GPL-2 This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2, as published by the Free Software Foundation. . This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. . You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. . On Debian systems, the complete text of the GNU General Public License version 2 can be found in '/usr/share/common-licenses/GPL-2'. ``` ## [golang-lru](https://github.com/hashicorp/golang-lru) ``` Copyright © 2014 HashiCorp, Inc. Mozilla Public License, version 2.0 1. Definitions 1.1. "Contributor" means each individual or legal entity that creates, contributes to the creation of, or owns Covered Software. 1.2. "Contributor Version" means the combination of the Contributions of others (if any) used by a Contributor and that particular Contributor's Contribution. 1.3. "Contribution" means Covered Software of a particular Contributor. 1.4. "Covered Software" means Source Code Form to which the initial Contributor has attached the notice in Exhibit A, the Executable Form of such Source Code Form, and Modifications of such Source Code Form, in each case including portions thereof. 1.5. "Incompatible With Secondary Licenses" means a. that the initial Contributor has attached the notice described in Exhibit B to the Covered Software; or b. that the Covered Software was made available under the terms of version 1.1 or earlier of the License, but not also under the terms of a Secondary License. 1.6. "Executable Form" means any form of the work other than Source Code Form. 1.7. "Larger Work" means a work that combines Covered Software with other material, in a separate file or files, that is not Covered Software. 1.8. "License" means this document. 1.9. "Licensable" means having the right to grant, to the maximum extent possible, whether at the time of the initial grant or subsequently, any and all of the rights conveyed by this License. 1.10. "Modifications" means any of the following: a. any file in Source Code Form that results from an addition to, deletion from, or modification of the contents of Covered Software; or b. any new file in Source Code Form that contains any Covered Software. 1.11. "Patent Claims" of a Contributor means any patent claim(s), including without limitation, method, process, and apparatus claims, in any patent Licensable by such Contributor that would be infringed, but for the grant of the License, by the making, using, selling, offering for sale, having made, import, or transfer of either its Contributions or its Contributor Version. 1.12. "Secondary License" means either the GNU General Public License, Version 2.0, the GNU Lesser General Public License, Version 2.1, the GNU Affero General Public License, Version 3.0, or any later versions of those licenses. 1.13. "Source Code Form" means the form of the work preferred for making modifications. 1.14. "You" (or "Your") means an individual or a legal entity exercising rights under this License. For legal entities, "You" includes any entity that controls, is controlled by, or is under common control with You. For purposes of this definition, "control" means (a) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (b) ownership of more than fifty percent (50%) of the outstanding shares or beneficial ownership of such entity. 2. License Grants and Conditions 2.1. Grants Each Contributor hereby grants You a world-wide, royalty-free, non-exclusive license: a. under intellectual property rights (other than patent or trademark) Licensable by such Contributor to use, reproduce, make available, modify, display, perform, distribute, and otherwise exploit its Contributions, either on an unmodified basis, with Modifications, or as part of a Larger Work; and b. under Patent Claims of such Contributor to make, use, sell, offer for sale, have made, import, and otherwise transfer either its Contributions or its Contributor Version. 2.2. Effective Date The licenses granted in Section 2.1 with respect to any Contribution become effective for each Contribution on the date the Contributor first distributes such Contribution. 2.3. Limitations on Grant Scope The licenses granted in this Section 2 are the only rights granted under this License. No additional rights or licenses will be implied from the distribution or licensing of Covered Software under this License. Notwithstanding Section 2.1(b) above, no patent license is granted by a Contributor: a. for any code that a Contributor has removed from Covered Software; or b. for infringements caused by: (i) Your and any other third party's modifications of Covered Software, or (ii) the combination of its Contributions with other software (except as part of its Contributor Version); or c. under Patent Claims infringed by Covered Software in the absence of its Contributions. This License does not grant any rights in the trademarks, service marks, or logos of any Contributor (except as may be necessary to comply with the notice requirements in Section 3.4). 2.4. Subsequent Licenses No Contributor makes additional grants as a result of Your choice to distribute the Covered Software under a subsequent version of this License (see Section 10.2) or under the terms of a Secondary License (if permitted under the terms of Section 3.3). 2.5. Representation Each Contributor represents that the Contributor believes its Contributions are its original creation(s) or it has sufficient rights to grant the rights to its Contributions conveyed by this License. 2.6. Fair Use This License is not intended to limit any rights You have under applicable copyright doctrines of fair use, fair dealing, or other equivalents. 2.7. Conditions Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted in Section 2.1. 3. Responsibilities 3.1. Distribution of Source Form All distribution of Covered Software in Source Code Form, including any Modifications that You create or to which You contribute, must be under the terms of this License. You must inform recipients that the Source Code Form of the Covered Software is governed by the terms of this License, and how they can obtain a copy of this License. You may not attempt to alter or restrict the recipients' rights in the Source Code Form. 3.2. Distribution of Executable Form If You distribute Covered Software in Executable Form then: a. such Covered Software must also be made available in Source Code Form, as described in Section 3.1, and You must inform recipients of the Executable Form how they can obtain a copy of such Source Code Form by reasonable means in a timely manner, at a charge no more than the cost of distribution to the recipient; and b. You may distribute such Executable Form under the terms of this License, or sublicense it under different terms, provided that the license for the Executable Form does not attempt to limit or alter the recipients' rights in the Source Code Form under this License. 3.3. Distribution of a Larger Work You may create and distribute a Larger Work under terms of Your choice, provided that You also comply with the requirements of this License for the Covered Software. If the Larger Work is a combination of Covered Software with a work governed by one or more Secondary Licenses, and the Covered Software is not Incompatible With Secondary Licenses, this License permits You to additionally distribute such Covered Software under the terms of such Secondary License(s), so that the recipient of the Larger Work may, at their option, further distribute the Covered Software under the terms of either this License or such Secondary License(s). 3.4. Notices You may not remove or alter the substance of any license notices (including copyright notices, patent notices, disclaimers of warranty, or limitations of liability) contained within the Source Code Form of the Covered Software, except that You may alter any license notices to the extent required to remedy known factual inaccuracies. 3.5. Application of Additional Terms You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations to one or more recipients of Covered Software. However, You may do so only on Your own behalf, and not on behalf of any Contributor. You must make it absolutely clear that any such warranty, support, indemnity, or liability obligation is offered by You alone, and You hereby agree to indemnify every Contributor for any liability incurred by such Contributor as a result of warranty, support, indemnity or liability terms You offer. You may include additional disclaimers of warranty and limitations of liability specific to any jurisdiction. 4. Inability to Comply Due to Statute or Regulation If it is impossible for You to comply with any of the terms of this License with respect to some or all of the Covered Software due to statute, judicial order, or regulation then You must: (a) comply with the terms of this License to the maximum extent possible; and (b) describe the limitations and the code they affect. Such description must be placed in a text file included with all distributions of the Covered Software under this License. Except to the extent prohibited by statute or regulation, such description must be sufficiently detailed for a recipient of ordinary skill to be able to understand it. 5. Termination 5.1. The rights granted under this License will terminate automatically if You fail to comply with any of its terms. However, if You become compliant, then the rights granted under this License from a particular Contributor are reinstated (a) provisionally, unless and until such Contributor explicitly and finally terminates Your grants, and (b) on an ongoing basis, if such Contributor fails to notify You of the non-compliance by some reasonable means prior to 60 days after You have come back into compliance. Moreover, Your grants from a particular Contributor are reinstated on an ongoing basis if such Contributor notifies You of the non-compliance by some reasonable means, this is the first time You have received notice of non-compliance with this License from such Contributor, and You become compliant prior to 30 days after Your receipt of the notice. 5.2. If You initiate litigation against any entity by asserting a patent infringement claim (excluding declaratory judgment actions, counter-claims, and cross-claims) alleging that a Contributor Version directly or indirectly infringes any patent, then the rights granted to You by any and all Contributors for the Covered Software under Section 2.1 of this License shall terminate. 5.3. In the event of termination under Sections 5.1 or 5.2 above, all end user license agreements (excluding distributors and resellers) which have been validly granted by You or Your distributors under this License prior to termination shall survive termination. 6. Disclaimer of Warranty Covered Software is provided under this License on an "as is" basis, without warranty of any kind, either expressed, implied, or statutory, including, without limitation, warranties that the Covered Software is free of defects, merchantable, fit for a particular purpose or non-infringing. The entire risk as to the quality and performance of the Covered Software is with You. Should any Covered Software prove defective in any respect, You (not any Contributor) assume the cost of any necessary servicing, repair, or correction. This disclaimer of warranty constitutes an essential part of this License. No use of any Covered Software is authorized under this License except under this disclaimer. 7. Limitation of Liability Under no circumstances and under no legal theory, whether tort (including negligence), contract, or otherwise, shall any Contributor, or anyone who distributes Covered Software as permitted above, be liable to You for any direct, indirect, special, incidental, or consequential damages of any character including, without limitation, damages for lost profits, loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses, even if such party shall have been informed of the possibility of such damages. This limitation of liability shall not apply to liability for death or personal injury resulting from such party's negligence to the extent applicable law prohibits such limitation. Some jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, so this exclusion and limitation may not apply to You. 8. Litigation Any litigation relating to this License may be brought only in the courts of a jurisdiction where the defendant maintains its principal place of business and such litigation shall be governed by laws of that jurisdiction, without reference to its conflict-of-law provisions. Nothing in this Section shall prevent a party's ability to bring cross-claims or counter-claims. 9. Miscellaneous This License represents the complete agreement concerning the subject matter hereof. If any provision of this License is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. Any law or regulation which provides that the language of a contract shall be construed against the drafter shall not be used to construe this License against a Contributor. 10. Versions of the License 10.1. New Versions Mozilla Foundation is the license steward. Except as provided in Section 10.3, no one other than the license steward has the right to modify or publish new versions of this License. Each version will be given a distinguishing version number. 10.2. Effect of New Versions You may distribute the Covered Software under the terms of the version of the License under which You originally received the Covered Software, or under the terms of any subsequent version published by the license steward. 10.3. Modified Versions If you create software not governed by this License, and you want to create a new license for such software, you may create and use a modified version of this License if you rename the license and remove any references to the name of the license steward (except to note that such modified license differs from this License). 10.4. Distributing Source Code Form that is Incompatible With Secondary Licenses If You choose to distribute Source Code Form that is Incompatible With Secondary Licenses under the terms of this version of the License, the notice described in Exhibit B of this License must be attached. Exhibit A - Source Code Form License Notice This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. If it is not possible or desirable to put the notice in a particular file, then You may include the notice in a location (such as a LICENSE file in a relevant directory) where a recipient would be likely to look for such a notice. You may add additional accurate notices of copyright ownership. Exhibit B - "Incompatible With Secondary Licenses" Notice This Source Code Form is "Incompatible With Secondary Licenses", as defined by the Mozilla Public License, v. 2.0. ```