如何解决Prefect作业在Azure AKS虚拟节点运行的ACI创建失败问题

问题场景 #

在Azure Kubernetes服务(AKS)虚拟节点上运行Prefect作业时，已添加推荐的nodeSelector与tolerations调度配置：

"nodeSelector": {
    "kubernetes.io/role": "agent",
    "beta.kubernetes.io/os": "linux",
    "type": "virtual-kubelet",
},
"tolerations": [
    {"key": "virtual-kubelet.io/provider", "operator": "Exists"},
    {"key": "azure.com/aci", "effect": "NoSchedule"},
],

容器创建阶段直接失败，抛出如下报错：

Warning   ProviderCreateFailed   pod/prefect-job-XXXXX-XXXXX   ACI does not support providing args without specifying the command. Please supply both command and args to the pod spec.

尝试过公开讨论中提到的多种command配置方案，均无法解决问题。

根因分析 #

AKS虚拟节点底层依托Azure Container Instance(ACI)实现，存在硬性校验规则：只要Pod spec中定义了args字段，就必须同时显式声明command字段，不允许直接复用容器镜像内置的ENTRYPOINT配置。
Prefect生成作业Pod时，默认只会注入运行时所需的args参数，不会显式覆写command字段，刚好触发ACI的校验限制。之前尝试的配置方案无效，核心原因是没有匹配Prefect镜像默认入口点的真实路径，或者错误覆盖了原有启动逻辑。

可行解决方案 #

按照以下步骤修改Prefect Kubernetes基础设施配置即可修复：

• 首先确认你使用的Prefect运行镜像的默认ENTRYPOINT路径，官方标准镜像的入口点为/opt/prefect/entrypoint.sh，自定义镜像可以本地执行docker inspect <你的镜像标签>查看Entrypoint字段的实际值。
• 在Kubernetes作业配置块中显式声明command字段，将镜像入口点、Prefect引擎启动命令按顺序填入数组，和自动注入的args字段成对出现，满足ACI的校验要求。
• 保留原有调度相关的nodeSelector、tolerations配置不变。

正确的配置参考示例：

from prefect.infrastructure import KubernetesJob

k8s_job_config = KubernetesJob(
    namespace="prefect-jobs", # 替换为实际使用的命名空间
    image="prefecthq/prefect:2.18-python3.11", # 替换为实际使用的Prefect镜像版本
    # 核心修复：显式指定command，不要省略
    command=["/opt/prefect/entrypoint.sh", "prefect", "engine", "start"],
    node_selector={
        "kubernetes.io/role": "agent",
        "beta.kubernetes.io/os": "linux",
        "type": "virtual-kubelet",
    },
    tolerations=[
        {"key": "virtual-kubelet.io/provider", "operator": "Exists"},
        {"key": "azure.com/aci", "effect": "NoSchedule"},
    ]
)
# 将配置保存后关联到对应部署/工作池即可
k8s_job_config.save("aks-virtual-node-job-profile", overwrite=True)

注意：不要将args内容全部拼接进command字段，也不要删除原有启动逻辑。Prefect运行时依赖自动注入的args参数拉取作业定义、上报执行状态，随意修改会导致作业启动后无法正常运行。

配置更新后重新提交作业，即可正常调度到虚拟节点启动运行，不会再出现ProviderCreateFailed类报错。

内容的提问来源于stack exchange，提问作者Nuno Silva