安装 InferNex Bridge

本指南介绍适用于 arm64 集群的 Alauda Build of InferNex Bridge v26.6.0,该版本已发布到 OLM alpha 频道。

前提条件

在安装 Alauda Build of InferNex Bridge 之前,请确保目标集群具备所需的平台和推理依赖。

必需依赖

依赖项类型说明
Kubernetes 集群平台一个正在运行且具有管理员访问权限的集群。
KServeOperator当使用 KServe LLMInferenceService 入口点时必需。声明的上游兼容范围为 KServe v0.17.0-v0.19.0。Alauda Build of KServe v0.16.1 也已通过验证。
Envoy Gateway 和 Gateway APIOperator / CRDs当通过 Gateway API 资源公开推理服务时必需。
Gateway API Inference ExtensionCRDs基于 InferencePool 的智能路由所必需。
Alauda Build of LeaderWorkerSet集群插件请在 InferNex Bridge 之前安装。controller 会监视 LeaderWorkerSet 资源,并将其用于多节点推理工作负载。
推理 runtime 先决条件runtime准备所选推理引擎所需的 NPU 节点、模型存储、runtime 模板、runtime 镜像和网络访问。
INFO

InferNexService 模式不要求用户先安装 InferNex 主 chart。operator 会安装 InferNex Bridge 控制平面;服务模板、推理 runtime 镜像、模型文件以及特定功能所需的 CRD 必须在部署推理服务之前单独准备。

此 Operator 安装的 CRD

Alauda Build of InferNex Bridge OLM bundle 会安装其受管弹性编排组件使用的两个产品 API 和三个 CRD:

CRD是否由此 operator 安装
infernexservices.infernex.infernex.io是
infernexserviceconfigs.infernex.infernex.io是
resourcescalinggroups.autoscaling.openfuyao.com是
elasticscalers.elasticscaler.io是
tidals.tidal.io是

以下 CRD 不会由此 OLM bundle 安装。请根据下面所示要求单独安装:

CRD来源项目何时需要安装方式
leaderworkersets.leaderworkerset.x-k8s.ioAlauda Build of LeaderWorkerSetInferNex Bridge controller 和多节点推理工作负载在安装 InferNex Bridge 之前,先按照 LeaderWorkerSet 安装指南 进行安装。
rolebasedgroups.workloads.x-k8s.ioRoleBasedGroup (RBG)显式使用 RoleBasedGroup 的 ResourceScalingGroup 目标使用上游 RBG v0.7.0 release manifest 进行安装。

rolebasedgroups.workloads.x-k8s.io CRD 由上游 RoleBasedGroup (RBG) 项目提供。它是一个条件依赖项,Deployment 或 LeaderWorkerSet 目标不需要它。要安装上游 RBG v0.7.0 controller 和 CRD,请使用带版本的 release manifest:

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/sgl-project/rbg/v0.7.0/deploy/kubectl/manifests.yaml

kubectl wait deployment/rbgs-controller-manager \
  --namespace rbgs-system \
  --for=condition=Available \
  --timeout=5m

kubectl get crd rolebasedgroups.workloads.x-k8s.io \
  -o jsonpath='{range .spec.versions[?(@.name=="v1alpha2")]}{.name}{" served="}{.served}{" storage="}{.storage}{"\n"}{end}'

预期结果为 v1alpha2 served=true storage=true。该 manifest 使用 docker.io/rolebasedgroup/rbgs-controller:v0.7.0-888ade7,其中提供了 arm64 镜像。对于断开连接的集群,请先将该镜像镜像到集群可访问的 registry,并在应用之前更新 manifest 中的镜像引用。

如需选择其他版本,请查看上游 RBG releases。

启用受管的 Tidal、ElasticScaler 或 ResourceScalingGroup 组件时,会部署其 controller 工作负载。诸如 Tidal 和 ElasticScaler 之类的扩缩容策略资源,仍必须由用户或平台工作流单独创建。

Runtime 模板和镜像

WARNING

operator 包会同步其声明的 relatedImages,但 OLM runtime 模板会保留其社区源引用。在创建推理服务之前,请配置平台镜像 allowlist 和重写规则,以便这些源引用在目标集群 registry 中解析为同步后的镜像。

模型服务镜像 hub.oepkgs.net/openfuyao/ascend/vllm-ascend:v0.18.0 不包含在 operator 的 relatedImages 中。在部署 NPU 推理服务之前,请获取 arm64 镜像,将其上传或镜像到目标 registry,并为完整的源引用添加镜像重写规则。请验证解析后的 Pod imageID;工作负载规格中仍保留源引用并不表示重写失败。

配置 ImageWhiteList

平台在上传 InferNex Bridge package 时会创建一个由 operator 管理的 ImageWhiteList。请勿手动创建或删除此对象。由 operator 管理的 ImageWhiteList 对象会由 olm-registry 进行调谐,删除后可能会被重新创建。

在创建推理服务之前,请确认生成的对象包含所需的源镜像引用以及源到目标的重写规则。请保留已经存在的无关条目。

下表显示了预期的仓库映射。每条规则都会保留原始镜像 tag。

源仓库<target-registry> 下的目标仓库
cr.openfuyao.cn/openfuyao/cache-indexer3rdparty/openfuyao/cache-indexer
cr.openfuyao.cn/openfuyao/proxy-server3rdparty/openfuyao/proxy-server
cr.openfuyao.cn/openfuyao/hermes-router3rdparty/openfuyao/hermes-router
cr.openfuyao.cn/openfuyao/hermes-router-tokenizer3rdparty/openfuyao/hermes-router-tokenizer
cr.openfuyao.cn/openfuyao/hermes-router-prediction3rdparty/openfuyao/hermes-router-prediction
hub.oepkgs.net/openfuyao/redis3rdparty/openfuyao/redis
cr.openfuyao.cn/openfuyao/tidal3rdparty/openfuyao/tidal
cr.openfuyao.cn/openfuyao/resource-scaling-group3rdparty/openfuyao/resource-scaling-group
cr.openfuyao.cn/openfuyao/elastic-scaler3rdparty/openfuyao/elastic-scaler
cr.openfuyao.cn/openfuyao/eagle-eye-hardware-monitor3rdparty/openfuyao/eagle-eye-hardware-monitor
cr.openfuyao.cn/openfuyao/eagle-eye-hardware-diagnosis3rdparty/openfuyao/eagle-eye-hardware-diagnosis
cr.openfuyao.cn/openfuyao/eagle-eye-network-performance-exporter3rdparty/openfuyao/eagle-eye-network-performance-exporter
hub.oepkgs.net/openfuyao/alpine/kubectl3rdparty/openfuyao/alpine/kubectl
hub.oepkgs.net/openfuyao/ascend/vllm-ascend3rdparty/openfuyao/ascend/vllm-ascend

最终对象中相关部分应如下所示。完整对象还包含其他 package 镜像和由平台管理的条目。

apiVersion: app.alauda.io/v1alpha1
kind: ImageWhiteList
metadata:
  name: infernex-bridge
  namespace: cpaas-system
spec:
  repoList:
    - cr.openfuyao.cn/openfuyao/cache-indexer:26.6.0
    - hub.oepkgs.net/openfuyao/ascend/vllm-ascend:v0.18.0
    - busybox:1.36.1
    - docker.io/library/busybox:1.36.1
  rewriteRules:
    - regexp: ^cr\.openfuyao\.cn/openfuyao/cache\-indexer:(.*)$
      replacement: <target-registry>/3rdparty/openfuyao/cache-indexer:${1}
    - regexp: ^hub\.oepkgs\.net/openfuyao/ascend/vllm\-ascend:(.*)$
      replacement: <target-registry>/3rdparty/openfuyao/ascend/vllm-ascend:${1}

必须显式添加 vllm-ascend 条目,因为该镜像不属于 operator 的 relatedImages。在创建推理工作负载之前,请先将 arm64 镜像导入目标 registry。例如:

export TARGET_REGISTRY='<target-registry-host:port>'

skopeo copy --all \
  docker://hub.oepkgs.net/openfuyao/ascend/vllm-ascend:v0.18.0 \
  "docker://${TARGET_REGISTRY}/3rdparty/openfuyao/ascend/vllm-ascend:v0.18.0"

对于 BusyBox,请在 repoList 中同时保留 busybox:1.36.1 和 docker.io/library/busybox:1.36.1,但不要添加自定义 BusyBox 重写规则。平台的 _default 规则会处理短名称和 Docker Hub 规范化。

你可以使用以下命令备份并编辑由 operator 管理的对象。如果该对象名称不同,可使用 kubectl get imagewhitelist -A 查找。

kubectl get imagewhitelist -n cpaas-system infernex-bridge -o yaml \
  > imagewhitelist-infernex-bridge-backup.yaml

kubectl edit imagewhitelist -n cpaas-system infernex-bridge

工作负载规格中可能仍会显示社区源镜像。只有当实际 Pod imageID 指向目标 registry 时,重写才算成功。package 内组件和 package 外 runtime 的解析方式应如下所示:

cache-indexer=<target-registry>/3rdparty/openfuyao/cache-indexer@sha256:...
main=<target-registry>/3rdparty/openfuyao/ascend/vllm-ascend@sha256:...

验证导入镜像的架构,并检查工作负载镜像 ID:

export TARGET_REGISTRY='<target-registry-host:port>'
export INFERENCE_NAMESPACE='<inference-service-namespace>'

crane config --platform=linux/arm64 \
  "${TARGET_REGISTRY}/3rdparty/openfuyao/ascend/vllm-ascend:v0.18.0" |
  python3 -c 'import json, sys; data=json.load(sys.stdin); assert data.get("architecture") == "arm64", data; print("arm64 image verified")'

kubectl get pods -n "${INFERENCE_NAMESPACE}" \
  -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{range .status.initContainerStatuses[*]}  init:{.name}{"="}{.imageID}{"\n"}{end}{range .status.containerStatuses[*]}  {.name}{"="}{.imageID}{"\n"}{end}{end}'

准备模型

模型制品不包含在 InferNex Bridge operator package 中。当选择 OCI 模型存储时,请使用 Alauda AI 模型目录准备一个 ModelCar。参见 模型存储。

INFO

Alauda OLM bundle 会为该版本示例中使用的 KServe LLMInferenceService API 版本注册 InferNex Bridge admission webhook,包括 serving.kserve.io/v1alpha2。当在 KServe LLMInferenceService 上设置 infernex.io/runtime: "true" 时,该 webhook 用于在准入阶段应用兼容性补丁;它本身不会创建或调谐 LLMInferenceService 资源。

可选依赖

依赖项适用对象说明
NATSEagle-Eye当启用 Eagle-Eye 硬件监控、诊断或网络性能采集时必需。Service 必须可通过 nats.nats:4222 访问。
kube-prometheus-stackEagle-Eye当平台监控需要抓取并展示 Eagle-Eye 指标时必需。

可选的 EagleEye 可观测性

Alauda OLM 模板默认禁用 EagleEye。禁用 EagleEye 不会影响推理引擎、aggregate 或 prefill-decode 部署模式、Mooncake、cache-indexer 或 PD-Orchestrator。它只会禁用以下可选可观测性工作负载:

组件功能
Hardware Monitor运行在加速器节点上,收集硬件状态信息。
Hardware Diagnosis提供硬件诊断处理和诊断日志。
Network Performance Exporter收集网络性能数据,并在端口 8222 上暴露指标。

在启用 EagleEye 之前,请确认 NATS 已具有就绪的 Service 和 endpoint:

kubectl get service -n nats nats
kubectl get endpointslice -n nats -l kubernetes.io/service-name=nats

EagleEye init container 会连接到 nats.nats:4222。如果该 endpoint 不可用,已启用的 EagleEye Pod 将停留在 init 阶段。

可在 InferNexService 或引用的 InferNexServiceConfig 中显式启用 EagleEye:

spec:
  components:
    eagleEye:
      hardwareMonitor:
        enabled: true
      hardwareDiagnosis:
        enabled: true
      networkPerformanceExporter:
        enabled: true

应用资源后,请验证推理服务命名空间中的可选工作负载:

kubectl get deployment,daemonset,service -n <inference-service-namespace> \
  -l infernex.io/owner=<infernex-service-name>

预期工作负载包括 EagleEye hardware diagnosis Deployment、hardware monitor DaemonSet 以及 network performance exporter DaemonSet。如果不需要 EagleEye,请将这三个子开关都保持为 false。

上传 Operator

从你的 Alauda 产品交付渠道获取 arm64 安装包: infernex-bridge.alpha.arm64.v26.6.0.tgz。

使用 violet 命令将其发布到平台仓库:

violet push --platform-address=<platform-access-address> --platform-username=<platform-admin> --platform-password=<platform-admin-password> infernex-bridge.alpha.arm64.v26.6.0.tgz

安装 Operator

在 管理员 视图中:

  1. 点击 Marketplace / OperatorHub。
  2. 在控制台顶部,从 Cluster 下拉列表中选择要安装 InferNex Bridge Operator 的目标集群。
  3. 搜索并选择 Alauda Build of InferNex Bridge,然后点击 Install。
  4. 选择 alpha Channel。
  5. 选择版本 v26.6.0。
  6. 保持 Installation Location 不变,默认应为 infernex-system。
  7. 在 Upgrade Strategy 中选择 Manual。
  8. 点击 Install。

验证

确认 Alauda Build of InferNex Bridge 磁贴显示以下状态之一:

  • Installing:安装正在进行中;请等待其变为 Installed。
  • Installed:安装已完成。

验证 operator controller 和 webhooks 是否正在运行:

kubectl get pods -n infernex-system
kubectl get crd \
  infernexservices.infernex.infernex.io \
  infernexserviceconfigs.infernex.infernex.io \
  resourcescalinggroups.autoscaling.openfuyao.com \
  elasticscalers.elasticscaler.io \
  tidals.tidal.io

kubectl get mutatingwebhookconfiguration -o json |
  python3 -c 'import json, sys; data=json.load(sys.stdin); versions={version for item in data["items"] for webhook in item.get("webhooks", []) for rule in webhook.get("rules", []) if "llminferenceservices" in rule.get("resources", []) for version in rule.get("apiVersions", [])}; assert "v1alpha2" in versions, versions; print("LLMInferenceService webhook versions:", sorted(versions))'

controller Pod 应为 Running,所有五个捆绑的 CRD 都应已建立,并且 LLMInferenceService mutating webhook 应包含 v1alpha2。

Community 示例

如需查看由 Community 维护的示例,请参见 InferNex Bridge v26.6.0 示例。

升级 Alauda Build of InferNex Bridge

  1. 备份现有自定义资源:

    kubectl get infernexservice,infernexserviceconfig -A -o yaml > infernex-bridge-backup.yaml
  2. 使用 violet 工具上传新版本的 Alauda Build of InferNex Bridge operator package。

  3. 进入 Administrator -> Marketplace -> OperatorHub 页面,找到 Alauda Build of InferNex Bridge,查看目标版本,然后点击 Confirm 以应用升级。

验证

升级后,确认 Alauda Build of InferNex Bridge 磁贴显示 Installed,并验证 controller 和 CRD 状态:

kubectl get pods -n infernex-system
kubectl get crd \
  infernexservices.infernex.infernex.io \
  infernexserviceconfigs.infernex.infernex.io \
  resourcescalinggroups.autoscaling.openfuyao.com \
  elasticscalers.elasticscaler.io \
  tidals.tidal.io

回滚

仅当上一版本的 CRD 与集群中已存储的自定义资源兼容时,才使用旧 package。在 OperatorHub 中,选择之前可用的版本,并确认手动升级操作。如果之前的版本不可用,请先使用 violet 上传其安装包。

回滚后,请验证 controller、CRD、推理服务、runtime 镜像 ID 以及一个具有代表性的推理请求。在自定义资源仍然存在时,不要删除这五个捆绑的 CRD;删除它们也会删除已存储的自定义资源。