Restart an Agent Sandbox container-Container Compute Service(ACS)-阿里云帮助中心

Background

During routine O&M of Agent Sandbox applications, you may need to restart running containers. Common scenarios include:

An application becomes unhealthy and requires a quick service recovery.
Periodic restarts are needed to mitigate issues such as memory leaks.
Only a specific container needs to be restarted, without recreating the entire Pod.

Kubernetes does not natively support restarting a single container in a running Pod. Typically, you must delete the Pod or perform a rolling restart of a Deployment, both of which can be disruptive. ACS Agent Sandbox provides the ContainerRecreateRequest custom resource definition (CRD) to restart a specific container within a Pod without affecting other containers.

Prerequisites and limitations

Confirm the following component versions on the Add-ons page of your cluster:
- ack-agent-sandbox-controller: The latest version.
- acs-virtual-node: version >= v2.18.0.
- ack-kruise: version >= 1.8.4.

Limitations

Constraint	Description
Pod status	The Pod must be in the `Running` state. The operation is not supported for Pods in other states.
Operation granularity	You can restart one or more containers within a specified Pod.
Init containers	Restarting Init containers is not supported.

Procedure

Whether data is retained after a container restart depends on the Instance Type.

Expand to view different Instance Type and their data retention details

Type	Agent Sandbox	Standard/Performance-enhanced
Container read/write layer	Retained You must enable the `ops.alibabacloud.com/pause-enabled: "true"` annotation.	Not retained
emptyDir volume	Retained	Retained
Persistent volume (PV/PVC)	Retained	Retained

Step 1: Create an Agent Sandbox

Allocate a sandbox instance from a Sandbox Set warm pool by using a SandboxClaim, or create one manually based on an Agent Sandbox Instance Type.

SandboxClaim

Sandboxes created in this way have the ops.alibabacloud.com/pause-enabled: "true" annotation enabled by default. No additional configuration is required. For more information, see the SandboxClaim method.

Manual creation

Use Agent Sandbox computing resources and configure the ops.alibabacloud.com/pause-enabled: "true" annotation to create a sandbox.

Save the following content as sandbox.yaml.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: code-interpreter
  namespace: default
  labels:
    app: code-interpreter
spec:
  replicas: 2
  selector:
    matchLabels:
      app: code-interpreter
  template:
    metadata:
      labels:
        app: code-interpreter
        alibabacloud.com/acs: "true"
        alibabacloud.com/compute-class: agent-sandbox  # Agent Sandbox instance type 
        alibabacloud.com/compute-qos: default          # Quality of computing resources: default/best-effort
      annotations:
        ops.alibabacloud.com/pause-enabled: "true"     # Enable data retention for the read/write layer
    spec:
      automountServiceAccountToken: false
      terminationGracePeriodSeconds: 30
      containers:
      - name: sandbox
        image: registry-cn-zhangjiakou-vpc.ack.aliyuncs.com/acs/code-interpreter:v1.6 # Replace with the region where your cluster is located.
        imagePullPolicy: IfNotPresent
        resources:
          limits:
            cpu: "1"
            memory: 1Gi
          requests:
            cpu: "1"
            memory: 1Gi
            ephemeral-storage: 30Gi

Create the resource.
```
kubectl apply -f sandbox.yaml
```
Confirm that the status of the target application Pod is Running.
```
kubectl get pod | grep code-interpreter
```

Step 2: Create a ContainerRecreateRequest

A ContainerRecreateRequest (CRR) is a CRD provided by ACS for Agent Sandbox that defines a restart operation for one or more containers within a specified Pod. For advanced configurations, see Container Restart.

Save the following content as crr.yaml.

The CRR resource must be created in the same namespace as the target Pod. Otherwise, the operation has no effect.

apiVersion: apps.kruise.io/v1alpha1
kind: ContainerRecreateRequest
metadata:
  namespace: <YOUR-NAMESPACE>    # The namespace of the target Pod
  name: <YOUR-CRR-NAME>          # The name of the CRR resource
spec:
  podName: <YOUR-POD-NAME>       # The name of the target Pod
  containers:                    # A list of container names to restart. You must provide at least one container name.
  - name: <CONTAINER-NAME-1>     # Container name 1
  - name: <CONTAINER-NAME-2>     # Container name 2

Key field descriptions:

metadata.namespace: The namespace where the target Pod is located.
spec.podName: The name of the target Pod.
spec.containers[].name: The names of the containers to restart. You can specify multiple containers.

Create the CRR resource.
```
kubectl apply -f crr.yaml
```

Step 3: Check the restart status

After you submit the CRR, run the following command to check the container restart status:

kubectl get containerrecreaterequest <YOUR-CRR-NAME> -n <YOUR-NAMESPACE> -o yaml

When status.phase is Completed and the phase of the corresponding container in containerRecreateStates is Succeeded, the container has restarted successfully. Example:

apiVersion: apps.kruise.io/v1alpha1
kind: ContainerRecreateRequest
metadata:
  ...
status:
  completionTime: '2026-05-27T08:04:35Z'
  containerRecreateStates:
    - name: main
      phase: Succeeded
  phase: Completed

Status field descriptions:

status.phase: The overall status of the CRR. Completed indicates that the restart process is complete.
containerRecreateStates[].phase: The restart result for an individual container. Succeeded indicates the container was restarted successfully.