Kubernetes-MCAD¶

这包含 TorchX Kubernetes_MCAD 调度器，可用于通过多集群应用程序调度程序 (MCAD) 在 Kubernetes 集群上运行 TorchX 组件。

先决条件¶

TorchX Kubernetes_MCAD 调度器依赖于 AppWrapper + MCAD。

安装 MCAD：参见部署多集群应用程序调度程序指南 https://github.com/project-codeflare/multi-cluster-app-dispatcher/blob/main/doc/deploy/deployment.md

此实现需要 MCAD v1.34.1 或更高版本。

TorchX 使用 torch.distributed.run 来运行分布式训练。

了解有关运行分布式训练器的更多信息 torchx.components.dist

class torchx.schedulers.kubernetes_mcad_scheduler.KubernetesMCADScheduler(session_name: str, client: Optional[ApiClient] = None, docker_client: Optional[DockerClient] = None)[source]¶

Bases: DockerWorkspaceMixin, Scheduler[KubernetesMCADOpts]

KubernetesMCADScheduler 是 TorchX 的一个调度器接口，用于与 Kubernetes 交互。

重要事项：Kubernetes 集群上需要安装 AppWrapper/MCAD。TorchX 需要为多副本/多角色执行进行群组调度。请注意，AppWrapper/MCAD 支持 Kubernetes 上所有应用程序包装作业之间的群组调度。但是，为了实现真正的群组调度，AppWrapper/MCAD 需要与额外的 Kubernetes 协同调度程序一起使用。有关安装说明，请参见： https://github.com/project-codeflare/multi-cluster-app-dispatcher/blob/main/doc/deploy/deployment.md

已确认此方法适用于 MCAD 主分支 v1.34.1 或更高版本，以及 OpenShift Kubernetes 客户端版本：4.10.13 服务器版本：4.9.18 Kubernetes 版本：v1.22.3+e790d7f

$ torchx run --scheduler kubernetes_mcad --scheduler_args namespace=default,image_repo=<your_image_repo> utils.echo --image alpine:latest --msg hello
...

TorchX-MCAD 调度器可与 Kubernetes 上的辅助调度程序一起使用。要启用此功能，用户必须提供协同调度程序的名称。使用此功能，将为每个 TorchX 角色定义一个 PodGroup，而协同调度程序将在 Kubernetes 集群上处理辅助调度。有关其他资源，请参见：1. PodGroup 和协同调度： https://github.com/kubernetes-sigs/scheduler-plugins/tree/release-1.24/pkg/coscheduling 2. 安装辅助调度程序： https://github.com/kubernetes-sigs/scheduler-plugins/blob/release-1.24/doc/install.md 3. PodGroup CRD： https://github.com/kubernetes-sigs/scheduler-plugins/blob/release-1.24/config/crd/bases/scheduling.sigs.k8s.io_podgroups.yaml

MCAD 调度程序支持 AppWrapper 级别的优先级，以及在具有 PriorityClass 定义的集群上可选的 Pod 级别的优先级。在 AppWrapper 级别，较高的整数值表示较高的优先级。Kubernetes 集群可能具有其他 PriorityClass 定义，这些定义可以应用于 Pod 级别。虽然可以在不同级别设置不同的优先级，但建议与您的 Kubernetes 集群管理员确认是否有其他指导方针。有关 Kubernetes PriorityClass 的更多信息，请参见： https://kubernetes.ac.cn/docs/concepts/scheduling-eviction/pod-priority-preemption/ 。

为了使用网络选项，Kubernetes 集群必须安装 multus。有关 multus 安装说明以及如何设置自定义网络附件定义，请参见： https://github.com/k8snetworkplumbingwg/multus-cni/blob/master/docs/how-to-use.md

配置选项

    usage:
        [namespace=NAMESPACE],[image_repo=IMAGE_REPO],[service_account=SERVICE_ACCOUNT],[priority=PRIORITY],[priority_class_name=PRIORITY_CLASS_NAME],[image_secret=IMAGE_SECRET],[coscheduler_name=COSCHEDULER_NAME],[network=NETWORK]

    optional arguments:
        namespace=NAMESPACE (str, default)
            Kubernetes namespace to schedule job in
        image_repo=IMAGE_REPO (str, None)
            The image repository to use when pushing patched images, must have push access. Ex: example.com/your/container
        service_account=SERVICE_ACCOUNT (str, None)
            The service account name to set on the pod specs
        priority=PRIORITY (int, None)
            The priority level to set on the job specs. Higher integer value means higher priority
        priority_class_name=PRIORITY_CLASS_NAME (str, None)
            Pod specific priority level. Check with your Kubernetes cluster admin if Priority classes are defined on your system
        image_secret=IMAGE_SECRET (str, None)
            The name of the Kubernetes/OpenShift secret set up for private images
        coscheduler_name=COSCHEDULER_NAME (str, None)
            Option to run TorchX-MCAD with a co-scheduler. User must provide the co-scheduler name.
        network=NETWORK (str, None)
            Name of additional pod-to-pod network beyond default Kubernetes network

挂载

挂载外部文件系统/卷是通过 HostPath 和 PersistentVolumeClaim 支持实现的。

hostPath 卷：type=bind,src=<host path>,dst=<container path>[,readonly]
PersistentVolumeClaim：type=volume,src=<claim>,dst=<container path>[,readonly]
主机设备：type=device,src=/dev/foo[,dst=<container path>][,perm=rwm] 如果您指定主机设备，则作业将在特权模式下运行，因为 Kubernetes 不会公开将 –device 传递到底层容器运行时的途径。用户应优先使用设备插件。

参见 torchx.specs.parse_mounts() 以获取更多信息。

外部文档： https://kubernetes.ac.cn/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 和内存。

兼容性

功能	调度程序支持
获取日志	✔️
分布式作业	✔️
取消作业	✔️
描述作业	✔️
工作区/修补	✔️
挂载	✔️
弹性	❌

describe(app_id: str) → Optional[DescribeAppResponse][source]¶

描述指定的应用程序。

返回值:: AppDef 描述或 None 如果应用程序不存在。

list() → List[ListAppResponse][source]¶: 对于在调度程序上启动的应用程序，此 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][source]¶

返回 k``th replica of the ``role 日志行的迭代器。迭代器在所有符合条件的日志行都被读取后结束。

如果调度程序支持基于时间的游标来获取自定义时间范围的日志行，则会遵守 since、until 字段，否则会忽略它们。不指定 since 和 until 等同于获取所有可用的日志行。如果 until 为空，则迭代器类似于 tail -f，一直跟踪日志输出，直到作业到达终端状态。

日志的具体定义是调度程序特定的。一些调度程序可能将 stderr 或 stdout 视为日志，而另一些调度程序可能从日志文件中读取日志。

行为和假设

如果在不存在的应用程序上调用，则会产生未定义的行为。调用方应使用 exists(app_id) 检查应用程序是否存在，然后再调用此方法。
没有状态，使用相同的参数两次调用此方法会返回一个新的迭代器。之前的迭代进度将丢失。
并不总是支持日志尾部跟踪。并非所有调度程序都支持实时日志迭代（例如，在应用程序运行时跟踪日志）。有关迭代器的行为，请参阅特定调度程序的文档。

3.1 如果调度程序支持日志尾部跟踪，则应由: should_tail 参数控制。

不保证日志保留。当调用此方法时，底层调度程序可能已经清除了此应用程序的日志记录。如果是这样，此方法会引发任意异常。
如果 should_tail 为 True，则该方法仅在所有可访问的日志行都被完全用尽并且应用程序已达到最终状态时引发 StopIteration 异常。例如，如果应用程序卡住并且没有生成任何日志行，则迭代器会阻塞，直到应用程序最终被杀死（通过超时或手动），然后引发 StopIteration。

如果 should_tail 为 False，则该方法在没有更多日志时引发 StopIteration。
并非所有调度程序都需要支持它。
一些调度程序可能通过支持 __getitem__ 来支持行游标（例如，iter[50] 跳转到第 50 行日志）。
保留空格，每行都应包含 \n。到
支持交互式进度条，返回的线条不需要包含 \n，但应在没有换行符的情况下打印它们，以正确处理 \r 回车符。

参数:: streams – 要选择的 IO 输出流。其中之一：combined、stdout、stderr。如果调度程序不支持所选流，它将抛出 ValueError。
返回值:: 指定的角色副本的日志行的 Iterator
引发:: NotImplementedError – 如果调度程序不支持日志迭代

run_opts() → runopts[source]¶: 返回调度程序期望的运行配置选项。基本上是 --help 用于 run API。

schedule(dryrun_info: AppDryRunInfo[KubernetesMCADJob]) → str[source]¶

与 submit 相同，只是它接受一个 AppDryRunInfo。实现者鼓励实现此方法，而不是直接实现 submit，因为 submit 可以通过

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

class torchx.schedulers.kubernetes_mcad_scheduler.KubernetesMCADJob(images_to_push: Dict[str, Tuple[str, str]], resource: Dict[str, object])[source]¶

参考¶

torchx.schedulers.kubernetes_mcad_scheduler.create_scheduler(session_name: str, client: Optional[ApiClient] = None, docker_client: Optional[DockerClient] = None, **kwargs: Any) → KubernetesMCADScheduler[source]¶

torchx.schedulers.kubernetes_mcad_scheduler.app_to_resource(app: AppDef, namespace: str, service_account: Optional[str], image_secret: Optional[str], coscheduler_name: Optional[str], priority_class_name: Optional[str], network: Optional[str], priority: Optional[int] = None) → Dict[str, Any][source]¶

app_to_resource 从提供的 AppDef 创建 AppWrapper/MCAD Kubernetes 资源定义。资源定义可用于在 Kubernetes 上启动应用程序。

MCAD 支持应用程序级别的重试。在多个 TorchX 角色的情况下，AppWrapper 的最大重试次数设置为角色的最大重试次数的最小值。

torchx.schedulers.kubernetes_mcad_scheduler.mcad_svc(app: AppDef, svc_name: str, namespace: str, service_port: str) → V1Service[source]¶

torchx.schedulers.kubernetes_mcad_scheduler.get_appwrapper_status(app: Dict[str, str]) → AppState[source]¶

torchx.schedulers.kubernetes_mcad_scheduler.get_port_for_service(app: AppDef) → str[source]¶

torchx.schedulers.kubernetes_mcad_scheduler.get_role_information(generic_items: Iterable[Dict[str, Any]]) → Dict[str, Any][source]¶

torchx.schedulers.kubernetes_mcad_scheduler.get_tasks_status_description(status: Dict[str, str]) → Dict[str, int][source]¶

torchx.schedulers.kubernetes_mcad_scheduler.pod_labels(app: AppDef, role_idx: int, role: Role, replica_id: int, coscheduler_name: Optional[str], app_id: str) → Dict[str, str][source]¶

torchx.schedulers.kubernetes_mcad_scheduler.role_to_pod(name: str, unique_app_id: str, namespace: str, role: Role, service_account: Optional[str], image_secret: Optional[str], coscheduler_name: Optional[str], priority_class_name: Optional[str], network: Optional[str]) → V1Pod[source]¶

torchx.schedulers.kubernetes_mcad_scheduler.sanitize_for_serialization(obj: object) → object[source]¶

Kubernetes-MCAD¶

先决条件¶

参考¶

文档

教程

资源