#安装与配置

从 ACP Web Console 将 Alauda Build of Agent Sandbox 作为集群插件安装。当前产品和 ModulePlugin 版本为 v0.5.4-1；Helm Chart 版本为 0.5.4-1。

#前提条件

安装前，请确认：

• Agent Sandbox 软件包已在 ACP v4.4 原生应用中心中提供。
• 您拥有 ACP 平台管理员权限。
• 您已选择目标业务集群。
• 目标集群可以拉取 controller 镜像以及 Sandbox 工作负载所使用的镜像。
• 您可以对 global 集群和目标业务集群使用 kubectl。
• 您已为 Sandbox 资源规划业务命名空间。
• 任何必需的 RuntimeClass（例如 Kata Containers 或 gVisor）都已在业务集群中安装并正常运行。

#从 ACP Web Console 安装

1. 登录 ACP 并打开 管理员视图。
2. 转到 Marketplace > 集群插件。
3. 选择目标业务集群。
4. 找到 Alauda Container Platform Agent Sandbox（对于重命名之前发布的软件包，显示为 Alauda Build of Agent Sandbox），然后选择安装。
5. 选择版本 v0.5.4-1。
6. 配置下一节中介绍的 controller 设置。 7.提交安装并等待插件状态变为已安装。

默认安装会创建 agent-sandbox-system 命名空间，并启用核心 Sandbox controller。除非明确启用，否则可选扩展 controller 将保持禁用状态。

#Controller 配置

集群插件公开五项 controller 设置：

这些值仅配置 controller Deployment，不会配置业务 Sandbox 工作负载的资源、节点选择器、容忍度或 RuntimeClass。在 Sandbox.spec.podTemplate.spec 或相应的 SandboxTemplate 中配置工作负载行为。

replicaCount 必须至少为 1。应用渲染后的资源时，Kubernetes 会验证节点选择器和容忍度。对于 operator 为 Exists 的容忍度，请将 value 留空。tolerationSeconds 仅适用于 effect 为 NoExecute 的情况。

#验证安装

安装验证跨越两个集群边界。针对 global 集群运行 ModuleInfo 检查。针对所选业务集群运行 controller、CRD 和工作负载检查。

#Global 集群

验证集群插件的生命周期状态：

kubectl get moduleinfo -l cpaas.io/module-name=agent-sandbox

预期结果是一个 phase 为 Running 且版本为 v0.5.4-1 的 ModuleInfo。如果生命周期状态或版本不同，请停止操作并解决集群插件安装问题，然后再创建 Sandbox 资源。

#业务集群

首先确认当前上下文：

kubectl config current-context

仅当输出为目标业务集群时才继续。

验证 controller 的发布状态和可用性：

kubectl get deployment agent-sandbox-controller \
  -n agent-sandbox-system

kubectl rollout status deployment/agent-sandbox-controller \
  -n agent-sandbox-system \
  --timeout=180s

kubectl get deployment agent-sandbox-controller \
  -n agent-sandbox-system \
  -o custom-columns='DESIRED:.spec.replicas,READY:.status.readyReplicas,AVAILABLE:.status.availableReplicas'

READY 和 AVAILABLE 必须达到 DESIRED。

验证 API：

kubectl get crd sandboxes.agents.x-k8s.io
kubectl get crd sandboxtemplates.extensions.agents.x-k8s.io
kubectl get crd sandboxwarmpools.extensions.agents.x-k8s.io
kubectl get crd sandboxclaims.extensions.agents.x-k8s.io

验证 controller 参数和 Pod 配置：

kubectl get deployment agent-sandbox-controller \
  -n agent-sandbox-system \
  -o jsonpath='{.spec.template.spec.containers[0].args}{"\n"}'

kubectl get deployment agent-sandbox-controller \
  -n agent-sandbox-system \
  -o jsonpath='{.spec.template.spec.containers[0].resources}{"\n"}'

kubectl get deployment agent-sandbox-controller \
  -n agent-sandbox-system \
  -o jsonpath='{.spec.template.spec.nodeSelector}{"\n"}'

kubectl get deployment agent-sandbox-controller \
  -n agent-sandbox-system \
  -o jsonpath='{.spec.template.spec.tolerations}{"\n"}'

扩展 CRD 可以在扩展 reconciliation 仍处于禁用状态时安装。在使用扩展资源之前，请确认 controller 参数中包含 --extensions=true。

#更新配置

使用 Update 可在不更改已安装插件版本的情况下更改设置：

1. 在 Administrator > Marketplace > Cluster Plugins 中打开已安装的集群插件。
2. 选择 Update。
3. 更改相同的五个 controller 设置中的一个或多个。
4. 提交更新。
5. 等待 controller Deployment rollout 完成。
6. 重新运行全局集群和业务集群验证命令。

ACP 会将更新后的 ModuleInfo 配置渲染为 Helm values，并应用生成的 AppRelease。请勿通过直接编辑 ModuleInfo、Helm release 或 agent-sandbox-controller 来绕过集群插件管理。

#升级插件

使用 Upgrade 可切换到不同的 Agent Sandbox 版本。升级前请查看 Lifecycle Policy 和 Release Notes。

由于客户端可能需要针对持久化的 Suspended 条件、PodTerminating 原因以及不可变的 volumeClaimTemplates 进行更改，此版本的升级风险为 High。