Kubernetes-MCAD

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

预备知识

TorchX Kubernetes_MCAD调度程序依赖于AppWrapper + MCAD。

安装MCAD： 查看部署Multi-Cluster-Application-Dispatcher指南 https://github.com/project-codeflare/multi-cluster-app-dispatcher/blob/main/doc/deploy/deployment.md

此实现需要 MCAD 1.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)

基础： DockerWorkspaceMixin, Scheduler[KubernetesMCADOpts]

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

重要：AppWrapper/MCAD 需要在 Kubernetes 集群上安装。 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. PodGroups和辅助调度：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 卷： 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.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]

描述指定的应用程序。

Returns:

应用程序定义描述或 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 replica of the ``role。 该迭代器在读取完所有符合条件的日志行后结束。

如果调度程序支持基于时间指针获取日志行，则since，until字段会被遵循，否则会被忽略。不指定since和until相当于获取所有可用的日志行。如果until为空，则迭代器的行为就像tail -f一样，跟随日志输出直到作业达到终端状态。

日志的确切定义取决于调度程序的具体设置。有些调度程序可能会将标准错误或标准输出视为日志，而其他调度程序则可能从日志文件中读取日志。

行为和假设：

1. 如果在不存在的应用程序上调用此方法，会产生未定义行为。 调用者应在调用此方法之前使用exists(app_id)检查应用程序是否存在。

2. 不是有状态的，用相同的参数调用此方法两次 会返回一个新的迭代器。之前的迭代 进度会丢失。

3. 不一定始终支持日志追尾功能。并非所有调度器都支持实时日志迭代（例如，在应用程序运行时追尾日志）。有关迭代器的行为，请参阅特定调度器的文档。

3.1 If the scheduler supports log-tailing, it should be controlled

by should_tail parameter.

4. 不保证日志保留。调用此方法时，底层调度程序可能已经清除了该应用程序的日志记录。如果是这样的话，此方法将引发任意异常。

5. 如果 should_tail 为 True，该方法仅在可访问的日志行已完全耗尽且应用程序达到最终状态时抛出 StopIteration 异常。 例如，如果应用程序卡住且没有生成任何日志行，则迭代器会阻塞直到应用程序最终被终止（通过超时或手动操作），此时它会抛出一个 StopIteration 异常。

   如果 should_tail 是 False，该方法在没有更多日志时抛出 StopIteration。

6. 不一定由所有调度器支持。

7. 某些调度器可能通过支持 __getitem__ （例如，iter[50] 寻找第 50 行日志）来支持行光标。

8. Whitespace is preserved, each new line should include \n. To

   支持交互式进度条，返回的行不需要包含 \n，但应该在不换行的情况下打印，以正确处理 \r 回车符。

Parameters:

流 – 要选择的IO输出流。 选项之一：combined、stdout、stderr。 如果所选流不被调度程序支持，它将抛出一个ValueError异常。

Returns:

一个指定角色副本的日志行上的 Iterator

Raises:

NotImplementedError – 如果调度器不支持日志迭代

run_opts() → runopts

返回调度程序所期望的运行配置选项。 基本上是--help的run API。

schedule(dryrun_info: AppDryRunInfo[KubernetesMCADJob]) → str

与 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])

参考

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

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]

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

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

torchx.schedulers.kubernetes_mcad_scheduler.get_port_for_service(app: AppDef) → str

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

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

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]

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

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