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]¶

基础类: DockerWorkspaceMixin, Scheduler[KubernetesMCADOpts]

KubernetesMCADScheduler 是一个 TorchX 调度接口，用于 Kubernetes。

重要提示：需要在Kubernetes集群上安装AppWrapper/MCAD。 TorchX需要gang调度来执行多副本/多角色任务。请注意，AppWrapper/MCAD支持在Kubernetes上任何应用包装的作业之间进行gang调度。然而，为了实现真正的gang调度，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上的次级调度器一起使用。要启用此功能，用户必须提供coscheduler的名称。通过此功能，为每个TorchX角色定义了一个PodGroup，并且coscheduler 处理Kubernetes集群上的次级调度。有关更多资源，请参阅： 1. PodGroups和Coscheduling: 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.io/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= path>,dst= path>[,readonly]
持久卷声明：type=volume,src=,dst= path>[,readonly]
主机设备：type=device,src=/dev/foo[,dst= path>][,perm=rwm] 如果您指定了主机设备，作业将以特权模式运行，因为 Kubernetes 没有提供将 –device 传递给底层容器运行时的方法。用户应优先使用设备插件。

查看 torchx.specs.parse_mounts() 获取更多信息。

外部文档: https://kubernetes.io/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]¶

描述指定的应用程序。

Returns:: 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 If the scheduler supports log-tailing, it should be controlled: 通过 should_tail 参数。

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

如果 should_tail 为 False，当没有更多日志时，该方法会引发 StopIteration。
不需要所有调度程序都支持。
一些调度器可能通过支持__getitem__来支持行光标（例如iter[50]跳转到第50条日志行）。
Whitespace is preserved, each new line should include \n. To
支持交互式进度条，返回的行不需要包含\n，但应在打印时不换行以正确处理\r回车符。

Parameters:: streams – 要选择的IO输出流。选项之一：combined, stdout, stderr。如果调度程序不支持所选的流，它将抛出一个ValueError。
Returns:: 一个Iterator，用于遍历指定角色副本的日志行
Raises:: 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 支持在 APPLICATION 级别进行重试。在多个 TorchX Roles 的情况下，AppWrapper 的最大重试次数设置为角色中 max_retries 的最小值。

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: 角色, 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: 角色, 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]¶