#Install and Configure

Install Alauda Build of Agent Sandbox as a Cluster Plugin from the ACP Web Console. The current product and ModulePlugin version is v0.5.4-1; the Helm Chart version is 0.5.4-1.

#Prerequisites

Before installation, confirm that:

• The Agent Sandbox package is available in the ACP v4.4 Application Center.
• You have ACP platform-administrator permissions.
• You have selected the target workload cluster.
• The target cluster can pull the controller image and the images used by Sandbox workloads.
• You can use kubectl against both the global cluster and the target workload cluster.
• You have planned a business namespace for Sandbox resources.
• Any required RuntimeClass, such as Kata Containers or gVisor, is already installed and operational in the workload cluster.

#Install from ACP Web Console

1. Sign in to ACP and open the Administrator view.
2. Go to Marketplace > Cluster Plugins.
3. Select the target workload cluster.
4. Find Alauda Container Platform Agent Sandbox (shown as Alauda Build of Agent Sandbox for a package published before the rename) and select Install.
5. Select version v0.5.4-1.
6. Configure the controller settings described in the next section.
7. Submit the installation and wait until the plugin status is Installed.

The default installation creates the agent-sandbox-system namespace and enables the core Sandbox controller. Optional extension controllers remain disabled unless you enable them explicitly.

#Controller Configuration

The Cluster Plugin exposes five controller settings:

These values configure the controller Deployment only. They do not configure the resources, node selector, tolerations, or RuntimeClass of business Sandbox workloads. Configure workload behavior in Sandbox.spec.podTemplate.spec or the corresponding SandboxTemplate.

replicaCount must be at least 1. Kubernetes validates node selectors and tolerations when the rendered resources are applied. For a toleration with operator Exists, leave value empty. tolerationSeconds only applies to effect NoExecute.

#Verify the Installation

Installation verification crosses two cluster boundaries. Run the ModuleInfo check against the global cluster. Run controller, CRD, and workload checks against the selected workload cluster.

#Global Cluster

Verify the Cluster Plugin lifecycle state:

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

The expected result is a ModuleInfo with phase Running and version v0.5.4-1. If the lifecycle state or version is different, stop and resolve the Cluster Plugin installation before creating Sandbox resources.

#Workload Cluster

First confirm the active context:

kubectl config current-context

Continue only when the output is the intended workload cluster.

Verify the controller rollout and availability:

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 and AVAILABLE must reach DESIRED.

Verify the APIs:

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

Verify controller arguments and Pod configuration:

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"}'

Extension CRDs can be installed while extension reconciliation remains disabled. Before using extension resources, confirm that the controller arguments contain --extensions=true.

#Update Configuration

Use Update to change settings without changing the installed plugin version:

1. Open the installed Cluster Plugin in Administrator > Marketplace > Cluster Plugins.
2. Select Update.
3. Change one or more of the same five controller settings.
4. Submit the update.
5. Wait for the controller Deployment rollout to complete.
6. Re-run the global and workload-cluster verification commands.

ACP renders the updated ModuleInfo configuration into Helm values and applies the resulting AppRelease. Do not bypass Cluster Plugin management by editing ModuleInfo, the Helm release, or agent-sandbox-controller directly.

#Upgrade the Plugin

Use Upgrade to move to a different Agent Sandbox version. Review the Lifecycle Policy and Release Notes before upgrading.

This release has a High upgrade risk because clients may need changes for the persistent Suspended condition, the PodTerminating reason, and immutable volumeClaimTemplates.