容器计算服务 ACS：升级Agent Sandbox

以下示例创建一个 SandboxUpdateOps，将容器镜像升级到新版本，并通过 Lifecycle 钩子在升级前后备份和恢复数据。以下示例为备份OpenClaw工作空间（.openclaw）到/backup（动态挂载的OSS目录），进而在升级后进行恢复，可根据实际情况调整备份和恢复命令：

建议将工作目录打包压缩，避免 OSS 小文件 I/O 性能问题。

apiVersion: agents.kruise.io/v1alpha1
kind: SandboxUpdateOps
metadata:
  name: upgrade-demo
spec:
  selector:
    matchLabels:
      agents.kruise.io/sandbox-template: openclaw-sbs
  updateStrategy:
    maxUnavailable: 10%
  patch:
    spec:
      containers:
        - name: gateway
          image: ghcr.io/openclaw/openclaw:2026.4.11  # 替换成您的新版本镜像
  lifecycle:
    preUpgrade:
      exec:
        command:
          - /bin/bash
          - -c
          - |
            set -e
            cd /root/
            tar -czf openclaw-state-v1.tgz .openclaw
            mv openclaw-state-v1.tgz /backup
            echo 'preUpgrade success'
      timeoutSeconds: 600
    postUpgrade:
      exec:
        command:
          - /bin/bash
          - -c
          - |
            set -e
            rm -rf /root/.openclaw
            cp /backup/openclaw-state-v1.tgz /root/openclaw-state-v1.tgz
            tar -xzvf /root/openclaw-state-v1.tgz -C /root
            rm -rf /root/openclaw-state-v1.tgz
      timeoutSeconds: 600

字段说明：

• selector：通过 Label 选择需要升级的 Sandbox，支持 matchLabels 和 matchExpressions 两种方式。详情请参见 Kubernetes Labels and Selectors。

• updateStrategy.maxUnavailable：升级过程中同一时间最大不可用的 Sandbox 数量，默认值为 1。支持设置为绝对值或百分比（百分比以选中的 Sandbox 总数为基数计算）。

• patch：JSON 或 YAML 格式的补丁内容，以 Strategic Merge Patch（策略合并补丁）的方式应用到 Sandbox 的 template。

• lifecycle：升级生命周期钩子。

  • preUpgrade：升级前执行的备份命令。上述示例将工作目录文件备份到动态挂载的 OSS 目录。

  • postUpgrade：升级后执行的恢复命令。上述示例将 OSS 目录中的备份数据恢复到工作目录。

以下示例展示了 patch 的三种常见操作：更新容器镜像、增加 Volume 和删除 Volume。

apiVersion: agents.kruise.io/v1alpha1
kind: SandboxUpdateOps
spec:
  patch:
    spec:
      containers:
      - name: test-container
        # 更新容器镜像
        image: mirrors-ssl.aliyuncs.com/centos:8
        volumeMounts:
        # 删除原有的 Volume 挂载点 (根据 mountPath 定位)
        - $patch: delete
          mountPath: /mnt/volume2
        # 增加新的 Volume 挂载点
        - name: volume3
          mountPath: /mnt/volume3
      volumes:
      # 删除 Pod 级别的 Volume 定义 (根据 name 定位)
      - name: volume2
        $patch: delete
      # 增加 Pod 级别的 Volume 定义
      - name: volume3
        emptyDir: {}

上述示例完成三项修改：

• 更新：将容器 test-container 的镜像更新为 mirrors-ssl.aliyuncs.com/centos:8。

• 增加：添加 Volume volume3 及对应的 volumeMount。

• 删除：通过 $patch: delete 删除 Volume volume2 及对应的 volumeMount。

步骤一：定位失败阶段
查看Sandbox当前的状态，status.conditions 中的 reason表示当前升级所处阶段，message显示脚本报错信息：

kubectl get sandbox <name> -o yaml

apiVersion: agents.kruise.io/v1alpha1
kind: Sandbox
status:
  conditions:
  - lastTransitionTime: "2026-05-01T08:27:51Z"
    message: 'hook execution error: process error: exit status 1'
    reason: PreUpgradeFailed
    status: "False"
    type: Upgrading
  nodeName: virtual-kubelet-cn-hangzhou-i
  observedGeneration: 2
  phase: Upgrading

1. PreUpgradeFailed：前置脚本执行报错。

2. UpgradePodFailed：新 Pod 重建失败（镜像拉取、启动超时）。

3. PostUpgradeFailed：后置恢复脚本报错。

步骤二：继续升级或进行回滚

可根据Sandbox所处的升级失败阶段及实际业务场景选择继续升级或回滚。

• PreUpgrade阶段失败

  • 继续升级：修正spec.lifecycle.preUpgrade脚本逻辑后，删除原 SandboxUpdateOps 并重新创建即可。

  • 回滚：由于此时底层容器尚未重建，数据不会丢失。将SandboxUpdateOps的spec.patch配置回滚，且无需配置 Lifecycle（preUpgrade、postUpgrade）。

    SandboxUpdateOps YAML示例

    apiVersion: agents.kruise.io/v1alpha1
    kind: SandboxUpdateOps
    metadata:
      name: upgrade-demo
    spec:
      selector:
        matchLabels:
          agents.kruise.io/sandbox-template: openclaw-sbs
      updateStrategy:
        maxUnavailable: 10%
      patch:
        spec:
          containers:
            - name: gateway
              image: ghcr.io/openclaw/openclaw:2026.4.1  # 替换成您的老版本镜像

• UpgradePod阶段失败

  • 继续升级：修正主容器错误，如镜像拉取失败（替换SandboxUpdateOps spec.patch中的镜像）。注意：上一阶段中preUpgrade已经执行成功，需剔除preUpgrade配置（避免重复执行）。

    SandboxUpdateOps YAML示例

    apiVersion: agents.kruise.io/v1alpha1
    kind: SandboxUpdateOps
    metadata:
      name: upgrade-demo
    spec:
      selector:
        matchLabels:
          agents.kruise.io/sandbox-template: openclaw-sbs
      updateStrategy:
        maxUnavailable: 10%
      patch:
        spec:
          containers:
            - name: gateway
              image: ghcr.io/openclaw/openclaw:2026.4.1 # 替换成实际可用的镜像
      lifecycle:
        postUpgrade:
          exec:
            command:
              - /bin/bash
              - -c
              - |
                set -e
                rm -rf /root/.openclaw
                cp /backup/openclaw-state-v1.tgz /root/openclaw-state-v1.tgz
                tar -xzvf /root/openclaw-state-v1.tgz -C /root
                rm -rf /root/openclaw-state-v1.tgz
          timeoutSeconds: 600

  • 回滚：

    • 方式一（推荐）：如果升级前对 Sandbox 进行了 Checkpoint 备份，推荐使用Checkpoint功能克隆Agent Sandbox方式恢复。

    • 方式二：将SandboxUpdateOps的spec.patch配置回滚。注意：上一阶段中preUpgrade已经执行成功，需剔除preUpgrade配置（避免重复执行）。

      SandboxUpdateOps YAML示例

      apiVersion: agents.kruise.io/v1alpha1
      kind: SandboxUpdateOps
      metadata:
        name: upgrade-demo
      spec:
        selector:
          matchLabels:
            agents.kruise.io/sandbox-template: openclaw-sbs
        updateStrategy:
          maxUnavailable: 10%
        patch:
          spec:
            containers:
              - name: gateway
                image: ghcr.io/openclaw/openclaw:2026.4.1 # 替换成您的老版本镜像
        lifecycle:
          postUpgrade:
            exec:
              command:
                - /bin/bash
                - -c
                - |
                  set -e
                  rm -rf /root/.openclaw
                  cp /backup/openclaw-state-v1.tgz /root/openclaw-state-v1.tgz
                  tar -xzvf /root/openclaw-state-v1.tgz -C /root
                  rm -rf /root/openclaw-state-v1.tgz
            timeoutSeconds: 600

• PostUpgrade阶段失败

  • 继续升级：修正spec.lifecycle.postUpgrade脚本逻辑，剔除preUpgrade配置（上一阶段中preUpgrade已经执行成功，避免重复执行），然后删除原 SandboxUpdateOps 并重新创建即可。

    SandboxUpdateOps YAML示例

    apiVersion: agents.kruise.io/v1alpha1
    kind: SandboxUpdateOps
    metadata:
      name: upgrade-demo
    spec:
      selector:
        matchLabels:
          agents.kruise.io/sandbox-template: openclaw-sbs
      updateStrategy:
        maxUnavailable: 10%
      patch:
        spec:
          containers:
            - name: gateway
              image: ghcr.io/openclaw/openclaw:2026.4.11
      lifecycle:
        postUpgrade:
          exec:
            command:
              - /bin/bash
              - -c
              - |
                set -e
                rm -rf /root/.openclaw
                cp /backup/openclaw-state-v1.tgz /root/openclaw-state-v1.tgz
                tar -xzvf /root/openclaw-state-v1.tgz -C /root
                rm -rf /root/openclaw-state-v1.tgz
          timeoutSeconds: 600

  • 回滚：请参考UpgradePod阶段失败回滚方式。