#安装 Alauda AI

#操作步骤

在 Administrator 视图中：

1. 单击 Marketplace / OperatorHub。

2. 在控制台顶部的 Cluster 下拉列表中，选择要安装 Alauda AI 的目标集群。

3. 选择 Alauda AI，然后单击 Install。

   Install Alauda AI 窗口将弹出。

4. 然后在 Install Alauda AI 窗口中进行操作。

5. 保持 Channel 不变。

6. 检查 Version 是否与要安装的 Alauda AI 版本匹配。

7. 保持 Installation Location 不变，默认应为 aml-operator。

8. 将 Upgrade Strategy 选择为 Manual。

9. 单击 Install。

#验证

确认 Alauda AI 磁贴显示以下状态之一：

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

#部署 Alauda AI

在 Administrator 视图中：

1. 单击 Marketplace / OperatorHub。

2. 在控制台顶部的 Cluster 下拉列表中，选择要安装 Alauda AI Operator 的目标集群。

3. 选择 Alauda AI，然后单击它。

4. 在 Alauda AI 页面中，单击选项卡中的 All Instances。

5. 等待 default AmlCluster 实例出现，然后编辑它。

6. 从下拉列表中选择 Deploy Flavor：

   1. single-node 适用于非 HA 部署。
   2. ha-cluster 适用于 HA 集群部署（生产环境推荐）。

7. 在 Domain 字段中输入一个有效域名。

   INFO

   该域名由 ingress gateway 用于暴露模型服务。 大多数情况下，你会希望使用泛域名，例如 *.example.com。

   你可以通过更新 Domain Certificate Type 字段来指定以下证书类型：

   • Provided
   • SelfSigned
   • ACPDefaultIngress

   默认情况下，配置使用 SelfSigned 证书类型来保护到集群的 ingress 流量，证书存储在 Domain Certificate Secret 字段中指定的 knative-serving-cert secret 里。

#组件管理状态

Alauda AI 2.8 会自动安装并管理 AmlCluster 配置中选择的组件。以下值显示默认组件设置。请将你需要的条目合并到现有的 default AmlCluster 中；不要创建第二个实例。

spec:
  components:
    authorino:
      managementState: Managed
    envoyAIGateway:
      managementState: Unmanaged
    envoyGateway:
      managementState: SharedManaged
    feast:
      managementState: Unmanaged
    knativeServing:
      managementState: Unmanaged
      providerType: Operator
    llamaStack:
      managementState: Unmanaged
    lws:
      managementState: Managed
    mlflow:
      managementState: Unmanaged
    npuOperator:
      managementState: Unmanaged
      values:
        clusterd:
          enabled: false
        devicePlugin:
          enabled: true
        driver:
          enabled: true
          recoveryPolicy:
            autoRecover: false
          upgradePolicy:
            autoUpgrade: false
          version: 25.5.0
        exporter:
          enabled: true
        mindioacp:
          enabled: false
        mindiotft:
          enabled: false
        nodeD:
          enabled: false
        ociRuntime:
          enabled: true
        rscontroller:
          enabled: false
        trainer:
          enabled: false
    postgres:
      managementState: SharedManaged
    redis:
      managementState: SharedManaged
    servingRuntimeOperator:
      managementState: Unmanaged
    trustyAI:
      managementState: Unmanaged
    workbench:
      managementState: Unmanaged
      values:
        global:
          istio:
            enabled: false

spec.components 字段使用与以下产品和 Operator 对应的配置键：

管理状态含义如下：

对于常见的 2.8 部署，当需要相应能力时，请将以下组件开关设置为 Managed。servingRuntimeOperator 的设置取决于你环境中的加速器和 serving-runtime 要求。

spec:
  components:
    envoyAIGateway:
      managementState: Managed
    servingRuntimeOperator:
      managementState: Managed
    workbench:
      managementState: Managed

spec:
  components:
    knativeServing:
      managementState: SharedManaged

#配置 KServe

Alauda Build of KServe 由 Alauda AI 安装并管理。default AmlCluster 实例中的 kserve 组件默认值为 Managed，因此 Alauda AI 会安装 KServe Operator 并自动创建 KServe 实例。你无需上传 KServe Operator 软件包、从 OperatorHub 安装 Operator，或手动创建 KServe 自定义资源。

KServe 参数通过 spec.components.kserve.values 暴露。请将所需设置合并到现有的 default AmlCluster 中：

spec:
  components:
    kserve:
      managementState: Managed
      values:
        defaultDeploymentMode: RawDeployment
        domain: example.com
        ingressGateway: knative-serving/knative-ingress-gateway
        kserve:
          storage:
            uidModelcar: 1000
        preset:
          envoyAIGateway:
            port: 1063
            service: ai-gateway-controller
          envoyGateway:
            createInstance: true
            deployType: ControllerNamespace
            instanceName: aieg
            saNamespace: envoy-gateway-system
            serviceAccount: envoy-gateway
          gie:
            enabled: true
          kserveGateway:
            enabled: true
            name: kserve-ingress-gateway
            namespace: kserve
            port: 80
            service_type: NodePort

主要的 kserve 组件设置：

gateway 预设会配置位于推理流量前端的 AI gateway 栈：

验证 AmlCluster 是否已完成协调，以及 KServe 实例是否由 Alauda AI 创建：

kubectl get amlcluster default

kubectl get kserve default-kserve -n kserve-operator

当状态显示 DEPLOYED: True 时，AmlCluster 应报告 Phase=Ready 且 Reason=Reconciled，此时 KServe 实例即为就绪状态。

#配置自定义 OIDC 提供方（可选）

默认情况下，Alauda AI 使用 ACP Dex 作为 OIDC 提供方。在此默认配置下，AmlCluster 实例中不需要额外的 spec.oidc 配置。

如果你希望 Alauda AI 使用其他 OIDC 提供方，请在该提供方中注册 OAuth2/OIDC 客户端，允许 Alauda AI 回调 URL，然后更新 AmlCluster YAML 中的 spec.oidc。回调 URL 为：

https://<platform-address>/clusters/<cluster-name>/aml/oauth2/callback

Alauda AI 会从 Alauda AI 安装集群中 kubeflow 命名空间内的 Kubernetes Secret 读取 OIDC client secret。默认 Secret 名称为 aml-oidc-secret，Secret key 必须为 client-secret。请使用 OIDC 提供方中的 client secret 更新此 Secret：

kubectl create secret generic aml-oidc-secret \
  -n kubeflow \
  --from-literal=client-secret='<oidc-client-secret>' \
  --dry-run=client -o yaml | kubectl apply -f -

然后配置 spec.oidc：

spec:
  oidc:
    # OIDC issuer URL. This must match the issuer value advertised by the
    # provider, for example a Keycloak realm URL.
    issuerURL: https://<oidc-provider-issuer>
    # OAuth2/OIDC client ID registered in the external provider.
    clientID: <oidc-client-id>
    # Kubernetes Secret name in the kubeflow namespace. The Secret must
    # contain a client-secret key. Default: aml-oidc-secret.
    clientSecretName: aml-oidc-secret
    # OAuth2 scopes requested during login. Keep this minimal to avoid
    # oversized ID/access tokens and oversized login cookies.
    # Default: openid profile email.
    scope: openid profile email
    # Whether to use the preferred_username claim as the email value.
    # Default: true.
    preferredUsernameAsEmail: true
    main:
      # OIDC authorization endpoint. If you use discovery, this maps from
      # authorization_endpoint.
      loginURL: https://<oidc-provider-authorization-endpoint>
      # OAuth2 callback URL registered in the external provider.
      redirectURL: https://<platform-address>/clusters/<cluster-name>/aml/oauth2/callback

如果提供方在 <issuerURL>/.well-known/openid-configuration 暴露了标准 OIDC discovery 文档，那么当这些字段未设置时，Alauda AI 会从 discovery 中自动填充 redeemURL、jwksURL 和 profileURL。如果 discovery 不可用，请显式配置这些字段：

将映射后的 loginURL 值用于 main.loginURL；如果你配置了 secondary endpoint，则用于 secondary.loginURL。

spec:
  oidc:
    redeemURL: https://<oidc-provider-token-endpoint>
    jwksURL: https://<oidc-provider-jwks-endpoint>
    profileURL: https://<oidc-provider-userinfo-endpoint>

Keycloak 配置示例：

• 在目标 realm 中创建一个 OpenID Connect client。
• 将 Client ID 设置为 spec.oidc.clientID 中使用的值，例如 aml。
• 打开 Client authentication。
• 在 Authentication flow 下，选择 Standard flow。
• 打开 Require PKCE，并将 PKCE Method 设置为 S256。
• 将 Valid redirect URIs 设置为 https://<platform-address>/clusters/<cluster-name>/aml/*。
• 从 Keycloak client 的 Credentials 选项卡复制 client secret，并更新上面显示的 aml-oidc-secret Secret。
• 在 client 的 Client scopes 设置中，将 basic、email 和 profile 设为 Default，并将其他 scopes 设为 Optional，除非你的环境明确需要它们。除非必要，请避免添加较大的 claim mapper，例如 groups、realm roles、client roles、address、phone、offline access 以及其他应用特定的 claims。过大的 token 可能会导致 oauth2-proxy cookie 超过浏览器或 ingress header 大小限制，并引发登录循环或 HTTP 431/400 错误。

#配置控制台语言（可选）

Alauda AI 会从 AmlCluster 实例中的 spec.i18n.languages 读取可用的控制台语言。默认值为 en。

支持的语言代码如下：

en 和 zh 是内置语言。其他语言仅会添加为可选项。若要成功切换到这些语言，你还需要提供对应的翻译文件。

你可以在为其他语言准备翻译文件时，参考内置的英文和中文翻译文件：

/clusters/<cluster-name>/aml/console-aml/assets/i18n/en/lich-single.json
/clusters/<cluster-name>/aml/console-aml/assets/i18n/zh/lich-single.json

从这些文件生成目标语言的翻译，或者联系 Alauda 获取所需语言的最新翻译内容。

例如，若要在控制台中提供英文、中文和法语可选项，请更新 AmlCluster YAML：

spec:
  i18n:
    languages:
      - en
      - zh
      - fr

然后在 cpaas-system 命名空间中为法语创建一个翻译文件 ConfigMap：

apiVersion: v1
kind: ConfigMap
metadata:
  labels:
    image-load-config: "true"
  name: aml-i18n-fr
  namespace: cpaas-system
data:
  overrides: |
    [{
      "dest": "/aml-i18n/fr/lich-single.json",
      "configMap": {
         "name": "aml-i18n-fr",
         "key": "lich-single.json"
      }
    }]
  lich-single.json: |
    {
      "nav_model_repo": "Referentiel de modeles",
      "nav_infer_svc": "Service d'inference",
      "workbench": "Workbench",
      "tool": "Outils"
    }

其他非内置语言可使用相同模式：将 fr 替换为目标语言代码，并提供翻译后的 lich-single.json 内容。

#配置 Model Catalog

• Model OCI Registry Address：为 Model Catalog 托管模型 OCI 产物的 registry 地址。该字段没有默认值，必须根据你的环境进行配置。

  该 registry 存储 Model Catalog 使用的模型 OCI 镜像。请使用 Harbor 或其他启用 HTTPS 访问的生产模式 OCI registry。Model Catalog 不支持为拉取模型 OCI 镜像配置 imagePullSecret，因此用于 Model Catalog 的 Harbor project 或 repository 必须允许推理集群节点匿名拉取。在 Harbor 中，将存储 Model Catalog 镜像的 project 设为 Public。

  如果目标环境中无法部署支持 HTTPS 的 registry，可以将 HTTP registry 作为备用方案。在部署模型之前，请先在推理集群中的每个节点上配置容器运行时。对于 containerd，可为该 registry 地址添加 insecure registry mirror，例如创建 /etc/containerd/certs.d/<registry-host:port>/hosts.toml：

  server = "http://<registry-host:port>"
  
  [host."http://<registry-host:port>"]
    capabilities = ["pull", "resolve"]

  然后重启 containerd，或通过你的集群管理系统应用等效的节点运行时配置。该配置必须存在于调度推理服务 Pod 的节点上；否则，即使 Model Catalog 能列出该模型，Pod 的镜像拉取仍会失败。containerd 的具体配置路径可能因 Kubernetes 发行版而异；应用配置后，请验证节点能够拉取 Model Catalog 镜像，例如使用 crictl pull <registry-host:port>/<repository>:<tag>。

• Source of PVC：选择复用现有 PVC 还是创建新的 PVC。使用 CreateNew 可让安装过程创建 PVC。

• StorageClass Name：创建新 PVC 时使用的 StorageClass。

#验证

检查配置并保存 default AmlCluster 实例，然后查看其状态：

kubectl get amlcluster default

该资源应为 Ready：

NAME      PHASE   READY   REASON
default   Ready   True    Reconciled

#获取 OCI 镜像 tar 包

内置模型镜像以 OCI archive tar 包（符合 OCI Image Layout Specification 的 .tar 文件）形式交付。每个 tar 包都包含一个模型的多架构镜像（linux/amd64 + linux/arm64）。

你可以从 Customer Portal Marketplace 下载这些 tar 包，或者联系你的 Alauda 支持代表获取与 Alauda AI 版本匹配的软件包。

#推送到 Harbor

推荐的目标 registry 是 Harbor。下面的示例使用 HTTP Harbor registry。如果你的 Harbor registry 使用 HTTPS，请省略 --plain-http，并将 API URL 从 http:// 改为 https://。

在安装了 ctr、curl 和 jq 且可以访问 Harbor 的节点上运行这些命令。

首先，设置环境变量：

export REG=<harbor-address>:<port>
export REPO=mlops/modelcar-qwen3.5-0.8b       
export TAG=v0.1.0                             
export TAR=./Qwen3.5-0.8B.oci.tar             
export AUTH='user:password'

tar 包通常在 OCI image layout 中自带其标签（例如 v0.1.0）。如有需要，可从 tar 包中提取它：

export TAG=$(tar -xOf "$TAR" index.json \
  | jq -r '.manifests[0].annotations["org.opencontainers.image.ref.name"]')
echo "$TAG"   # should print something like v0.1.0

检查该镜像标签是否已存在于 Harbor 中：

URL="http://$REG/api/v2.0/projects/${REPO%%/*}/repositories/$(printf '%s' "${REPO#*/}" | sed 's|/|%2F|g')/artifacts/$TAG"

HTTP=$(curl -s -u "$AUTH" -o /tmp/harbor-artifact.json -w '%{http_code}' "$URL")

echo "HTTP=$HTTP  URL=$URL"

[ "$HTTP" = 200 ] && jq '{digest, size, push_time, arch: .extra_attrs.architecture, tags: [.tags[].name], platforms: [.references[]?.platform]}' /tmp/harbor-artifact.json \
  || jq -r '.errors[]?.message' /tmp/harbor-artifact.json

如果 Harbor project 还不存在，请在推送前先创建它：

PROJECT="${REPO%%/*}"

curl -s -u "$AUTH" -X POST "http://$REG/api/v2.0/projects" \
  -H 'Content-Type: application/json' \
  -d "{\"project_name\":\"$PROJECT\",\"public\":true}" \
  -w '\nHTTP %{http_code}\n'

如果 project 已存在，Harbor 会返回非 2xx 状态码。确认 project 存在后，请确保其配置为 public project，然后继续导入和推送。Model Catalog 不支持在部署模型 OCI 镜像时配置 imagePullSecret，因此推理集群节点必须能够匿名拉取这些镜像。

然后运行导入和推送操作步骤：

# 1. Import into the node's containerd content store.
#    --base-name prepends $REG/$REPO to the tag carried inside the tarball,
#    producing a fully-qualified reference $REG/$REPO:$TAG.
ctr -n k8s.io images import \
  --all-platforms \
  --base-name "$REG/$REPO" \
  "$TAR"

# 2. Verify the import. You should see "$REG/$REPO:$TAG".
ctr -n k8s.io images ls -q | grep "$REPO"

# 3. Push to Harbor. Use --plain-http only for HTTP Harbor.
ctr -n k8s.io images push \
  --plain-http \
  --user "$AUTH" \
  "$REG/$REPO:$TAG"

# 4. Clean up the local reference on the node. Blob data is reclaimed by
#    containerd's garbage collector, leaving no persistent state on the node.
ctr -n k8s.io images rm "$REG/$REPO:$TAG"

对每个内置模型 tar 包重复此操作步骤，并分别变更每个模型对应的 $REPO、$TAG 和 $TAR。

#验证 Harbor 导入

确认 Harbor 现在可以提供该镜像：

URL="http://$REG/api/v2.0/projects/${REPO%%/*}/repositories/$(printf '%s' "${REPO#*/}" | sed 's|/|%2F|g')/artifacts/$TAG"

HTTP=$(curl -s -u "$AUTH" -o /tmp/harbor-artifact.json -w '%{http_code}' "$URL")

echo "HTTP=$HTTP  URL=$URL"

[ "$HTTP" = 200 ] && jq '{digest, size, push_time, arch: .extra_attrs.architecture, tags: [.tags[].name], platforms: [.references[]?.platform]}' /tmp/harbor-artifact.json \
  || jq -r '.errors[]?.message' /tmp/harbor-artifact.json

HTTP=200 表示镜像已成功导入到 Harbor。期望输出中包含 digest、size、push time、tag 和平台信息：

{
  "digest": "sha256:...",
  "size": 123456789,
  "push_time": "2026-05-06T00:00:00.000Z",
  "arch": "amd64",
  "tags": ["v0.1.0"],
  "platforms": [
    {"architecture": "amd64", "os": "linux"},
    {"architecture": "arm64", "os": "linux"}
  ]
}