#安装 InferNex Bridge

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

#前提条件

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

#所需依赖

#本 operator 安装的 CRD

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

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

rolebasedgroups.workloads.x-k8s.io CRD 由上游 RoleBasedGroup (RBG) 项目 提供。它是一个条件依赖项，Deployment 或 LeaderWorkerSet 目标不需要它。要安装上游 RBG v0.7.0 控制器和 CRD，请使用带版本的发布清单：

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。该清单使用 docker.io/rolebasedgroup/rbgs-controller:v0.7.0-888ade7，它提供了 arm64 镜像。对于断开连接的集群，请将此镜像镜像到集群可访问的 registry，并在应用之前更新清单中的镜像引用。

在选择其他版本时，请参见上游 RBG releases。

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

#Runtime 模板和镜像

#配置 ImageWhiteList

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

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

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

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

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 时，重写才算成功。软件包内部组件和软件包外部 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 软件包中。当选择 OCI 模型存储时，请使用 Alauda AI 模型目录准备 ModelCar。请参见 模型存储。

#可选依赖

#可选的 EagleEye 可观测性

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

在启用 EagleEye 之前，请确认 NATS 具有就绪的 Service 和 endpoint：

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

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

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

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

应用资源后，请验证推理服务 namespace 中的可选工作负载：

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 安装包，然后按照 上架软件包 的说明上传该软件包。

#安装 operator

在 Administrator 视图中：

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 控制器和 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))'

控制器 Pod 应为 Running，所有五个捆绑的 CRD 都应已建立，且 LLMInferenceService mutating webhook 应包含 v1alpha2。

#社区示例

有关社区维护的示例，请参见 InferNex Bridge v26.6.0 examples。

#升级 Alauda Build of InferNex Bridge

1. 备份现有的自定义资源：

   kubectl get infernexservice,infernexserviceconfig -A -o yaml > infernex-bridge-backup.yaml

2. 按照 上架软件包 的说明上传新版 Alauda Build of InferNex Bridge operator 软件包。

3. 前往 Administrator -> Marketplace -> OperatorHub 页面，找到 Alauda Build of InferNex Bridge，查看目标版本，然后单击 Confirm 以应用。

#验证

升级后，确认 Alauda Build of InferNex Bridge 磁贴显示 Installed，并验证控制器和 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 与集群中已存储的自定义资源兼容时，才使用该旧软件包。在 OperatorHub 中，选择可用的上一个版本，并确认手动升级操作。如果该旧版本不可用，请先上传其安装包（参见 上架软件包）。

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