Kubernetes

這包含 TorchX Kubernetes 排程器，可用於在 Kubernetes 叢集上執行 TorchX 元件。

先決條件

TorchX Kubernetes 排程器依賴於 Volcano。如果您嘗試進行升級，則需要完全移除所有非 Job Volcano 資源並重新建立。

安裝 Volcano

kubectl apply -f https://raw.githubusercontent.com/volcano-sh/volcano/v1.6.0/installer/volcano-development.yaml

如需更多資訊，請參閱 Volcano 快速入門。

類別 torchx.schedulers.kubernetes_scheduler.KubernetesScheduler(session_name: str, client: Optional[ApiClient] = None, docker_client: Optional[DockerClient] = None)

基底： DockerWorkspaceMixin, Scheduler[KubernetesOpts]

KubernetesScheduler 是 TorchX 與 Kubernetes 之間的排程介面。

重要事項：Kubernetes 叢集上需要安裝 Volcano。TorchX 需要叢集排程才能執行多副本/多角色，而 Volcano 目前是 Kubernetes 唯一支援的排程器。如需安裝說明，請參閱：https://github.com/volcano-sh/volcano

這已確認可與 Volcano v1.3.0 和 Kubernetes 版本 v1.18-1.21 搭配使用。請參閱 https://github.com/pytorch/torchx/issues/120，其中追蹤了 Volcano 對 Kubernetes v1.22 的支援。

備註

如果重試次數超過 0 次的 AppDef 失敗，則可能不會將其顯示為 Pod。這是由於 Volcano 中已知的錯誤（根據 1.4.0 版本）：https://github.com/volcano-sh/volcano/issues/1651

$ pip install torchx[kubernetes]
$ torchx run --scheduler kubernetes --scheduler_args namespace=default,queue=test utils.echo --image alpine:latest --msg hello
kubernetes://torchx_user/1234
$ torchx status kubernetes://torchx_user/1234
...

設定選項

    usage:
        queue=QUEUE,[namespace=NAMESPACE],[service_account=SERVICE_ACCOUNT],[priority_class=PRIORITY_CLASS],[image_repo=IMAGE_REPO],[quiet=QUIET]

    required arguments:
        queue=QUEUE (str)
            Volcano queue to schedule job in

    optional arguments:
        namespace=NAMESPACE (str, default)
            Kubernetes namespace to schedule job in
        service_account=SERVICE_ACCOUNT (str, None)
            The service account name to set on the pod specs
        priority_class=PRIORITY_CLASS (str, None)
            The name of the PriorityClass to set on the job specs
        image_repo=IMAGE_REPO (str, None)
            (remote jobs) the image repository to use when pushing patched images, must have push access. Ex: example.com/your/container
        quiet=QUIET (bool, False)
            whether to suppress verbose output for image building. Defaults to ``False``.

掛載

掛載外部檔案系統/磁碟區是透過 HostPath 和 PersistentVolumeClaim 支援來完成的。

• hostPath 磁碟區：type=bind,src=<主機 路徑>,dst=<容器 路徑>[,readonly]

• PersistentVolumeClaim：type=volume,src=<宣告>,dst=<容器 路徑>[,readonly]

• 主機裝置：type=device,src=/dev/foo[,dst=<容器 路徑>][,perm=rwm] 如果您指定主機裝置，則作業將在具備權限的模式下執行，因為 Kubernetes 並未公開將 –device 傳遞至基礎容器執行階段的方法。使用者應該優先使用裝置外掛程式。

如需更多資訊，請參閱 torchx.specs.parse_mounts()。

外部文件：https://kubernetes.dev.org.tw/docs/concepts/storage/persistent-volumes/

資源/配置

若要選取特定的機器類型，您可以使用 node.kubernetes.io/instance-type 將功能新增至您的資源，這會將啟動的作業限制為該執行個體類型的節點。

>>> from torchx import specs
>>> specs.Resource(
...     cpu=4,
...     memMB=16000,
...     gpu=2,
...     capabilities={
...         "node.kubernetes.io/instance-type": "<cloud instance type>",
...     },
... )
Resource(...)

Kubernetes 可能會為主機保留一些記憶體。TorchX 假設您是在整個主機上進行排程，因此會自動減少資源請求量，以將節點保留的 CPU 和記憶體納入考量。如果您遇到排程問題，則可能需要減少從主機值請求的 CPU 和記憶體。

相容性

功能	排程器支援
擷取日誌	✔️
分散式作業	✔️
取消作業	✔️
描述作業	部分支援。KubernetesScheduler 會傳回作業和副本狀態，但不會提供完整的原始 AppSpec。
工作區/修補	✔️
掛載	✔️
彈性	需要 Volcano >1.6

describe(app_id: str) → Optional[DescribeAppResponse]

描述指定的應用程式。

傳回值:

AppDef 描述；如果應用程式不存在，則為 None。

list() → List[ListAppResponse]

對於在排程器上啟動的應用程式，此 API 會傳回 ListAppResponse 物件的清單，每個物件都具有應用程式 ID 及其狀態。備註：此 API 處於原型階段，可能會有所變更。

log_iter(app_id: str, role_name: str, k: int = 0, regex: Optional[str] = None, since: Optional[datetime] = None, until: Optional[datetime] = None, should_tail: bool = False, streams: Optional[Stream] = None) → Iterable[str]

傳回一個迭代器，指向 k``th 副本 的 ``角色 的日誌行。當所有符合條件的日誌行都已讀取完畢時，迭代器就會結束。

如果排程器支援基於時間的游標來擷取自訂時間範圍的日誌行，則會採用 since、until 欄位，否則會忽略它們。未指定 since 和 until 等同於取得所有可用的日誌行。如果 until 為空，則迭代器的行為類似於 tail -f，會持續追蹤日誌輸出，直到作業達到終止狀態為止。

日誌的確切定義因排程器而異。某些排程器可能會將 stderr 或 stdout 視為日誌，而其他排程器可能會從日誌檔案中讀取日誌。

行為和假設

1. 如果對不存在的應用程式呼叫，則會產生未定義的行為。呼叫者應在呼叫此方法之前，使用 exists(app_id) 檢查應用程式是否存在。

2. 不是有狀態的，使用相同的參數呼叫此方法兩次會傳回一個新的迭代器。先前的迭代進度會遺失。

3. 不一zh-TW: 定支援日誌追蹤。並非所有排程器都支援即時日誌迭代（例如，在應用程式執行時追蹤日誌）。有關迭代器的行為，請參閱特定排程器的說明文件。zh-CN: 定支持日志跟踪。并非所有调度器都支持实时日志迭代（例如，在应用程序运行时跟踪日志）。有关迭代器的行为，请参阅特定调度器的说明文档。

3.1 如果排程器支援日誌追蹤，則應由 should_tail 參數控制。

4. 不保證日誌保留。有可能在此方法被呼叫時，底層排程器可能已經清除了此應用程式的日誌記錄。如果是這樣，此方法會引發任意例外狀況。

5. 如果 should_tail 為 True，則該方法僅在可存取的日誌行已完全耗盡且應用程式已達到最終狀態時才會引發 StopIteration 例外狀況。例如，如果應用程式卡住且未產生任何日誌行，則迭代器會阻塞，直到應用程式最終被終止（透過逾時或手動），此時它會引發 StopIteration。

   如果 should_tail 為 False，則當沒有更多日誌時，該方法會引發 StopIteration。

6. 並非所有排程器都需要支援。

7. 某些排程器可以透過支援 __getitem__ 來支援行游標（例如，iter[50] 會搜尋到第 50 行日誌）。

8. 空格會被保留，每個新行都應該包含 \n。為了

   支援互動式進度條，傳回的行不需要包含 \n，但應該在沒有換行的情況下列印，以便正確處理 \r 歸位字元。

參數：

streams - 要選擇的 IO 輸出串流。選項有：combined、stdout、stderr。如果排程器不支援所選的串流，它會丟出 ValueError。

傳回值:

指定角色副本的日誌行的 Iterator

引發：

NotImplementedError - 如果排程器不支援日誌迭代

schedule(dryrun_info: AppDryRunInfo[KubernetesJob]) → str

與 submit 相同，但它採用 AppDryRunInfo。建議實作者實作此方法，而不是直接實作 submit，因為可以透過以下方式輕鬆實作 submit

dryrun_info = self.submit_dryrun(app, cfg)
return schedule(dryrun_info)

class torchx.schedulers.kubernetes_scheduler.KubernetesJob(images_to_push: Dict[str, Tuple[str, str]], resource: Dict[str, object])

參考

torchx.schedulers.kubernetes_scheduler.create_scheduler(session_name: str, client: Optional[ApiClient] = None, docker_client: Optional[DockerClient] = None, **kwargs: Any) → KubernetesScheduler

torchx.schedulers.kubernetes_scheduler.app_to_resource(app: AppDef, queue: str, service_account: Optional[str], priority_class: Optional[str] = None) → Dict[str, object]

app_to_resource 會根據提供的 AppDef 建立一個 volcano job kubernetes 資源定義。這個資源定義可用於在 Kubernetes 上啟動應用程式。

為了支援巨集，我們為每個副本產生一個任務，而不是使用 volcano 的 replicas 欄位，因為巨集會根據每個副本更改參數。

Volcano 有兩個層級的重試：一個在任務層級，另一個在作業層級。當使用 APPLICATION 重試策略時，作業層級的重試次數會設定為角色的 max_retries 的最小值。

torchx.schedulers.kubernetes_scheduler.pod_labels(app: AppDef, role_idx: int, role: Role, replica_id: int, app_id: str) → Dict[str, str]

torchx.schedulers.kubernetes_scheduler.role_to_pod(name: str, role: Role, service_account: Optional[str]) → V1Pod

torchx.schedulers.kubernetes_scheduler.sanitize_for_serialization(obj: object) → object