#Common Issues

Troubleshoot Agent Sandbox from the platform lifecycle inward: Cluster Plugin state, controller, APIs, Sandbox conditions, managed Pods, and then workload dependencies.

Before every command, confirm the active cluster and namespace:

kubectl config current-context
export BUSINESS_NAMESPACE=agent-demo

Run ModuleInfo checks against the global cluster. Run all controller, CRD, Sandbox, Pod, NetworkPolicy, RuntimeClass, and event checks against the target workload cluster.

#ModuleInfo Does Not Become Running

#Symptom

The Cluster Plugin installation or upgrade remains pending, failed, or reports a version different from v0.5.4-1.

#Checks

On the global cluster:

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

#Resolution

Resolve the ModuleInfo or AppRelease lifecycle error through the ACP Cluster Plugin workflow. Confirm that the selected package is v0.5.4-1 and that the target workload cluster is reachable. Do not bypass the platform by editing ModuleInfo, the Helm release, or the controller Deployment directly.

#Controller Deployment Is Not Ready

#Symptom

agent-sandbox-controller has unavailable replicas or its rollout times out.

#Checks

On the workload cluster:

kubectl get deployment,pod -n agent-sandbox-system
kubectl describe deployment agent-sandbox-controller -n agent-sandbox-system
kubectl get events -n agent-sandbox-system --sort-by=.lastTimestamp
kubectl logs deployment/agent-sandbox-controller \
  -n agent-sandbox-system \
  --tail=200

#Resolution

Use Pod status and events to correct image pull, resource, scheduling, security, or configuration errors. If a node selector or toleration makes the controller unschedulable, change the Cluster Plugin settings with Update and wait for a new rollout.

#Core or Extension CRDs Are Missing

#Symptom

The API server returns “the server doesn't have a resource type” for Sandbox or extension resources.

#Checks

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

#Resolution

Confirm that the Cluster Plugin installation completed successfully. Reconcile the installation through ACP. Do not apply an unrelated upstream manifest on top of the ACP-managed installation and do not create ad hoc CRD versions.

#Extension CRDs Exist but Resources Do Not Reconcile

#Symptom

SandboxTemplate, SandboxWarmPool, or SandboxClaim objects are accepted, but status does not change.

#Checks

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

kubectl get sandboxclaim,sandboxwarmpool,sandboxtemplate \
  -n "$BUSINESS_NAMESPACE"

kubectl get events -n "$BUSINESS_NAMESPACE" --sort-by=.lastTimestamp
kubectl logs deployment/agent-sandbox-controller \
  -n agent-sandbox-system \
  --tail=200

#Resolution

The controller arguments must contain --extensions=true. If not, use Cluster Plugin Update to enable extension controllers and wait for rollout completion. Also verify template and warm-pool reference names and required NetworkPolicies.

#Sandbox Does Not Become Ready

#Symptom

The Ready wait times out or the Sandbox reports Ready=False or DependenciesNotReady.

#Checks

kubectl get sandbox -n "$BUSINESS_NAMESPACE"
kubectl describe sandbox python-sandbox -n "$BUSINESS_NAMESPACE"
kubectl get pod -n "$BUSINESS_NAMESPACE" -o wide
kubectl describe pod python-sandbox -n "$BUSINESS_NAMESPACE"
kubectl get events -n "$BUSINESS_NAMESPACE" --sort-by=.lastTimestamp

Inspect all Sandbox conditions:

kubectl get sandbox python-sandbox \
  -n "$BUSINESS_NAMESPACE" \
  -o jsonpath='{range .status.conditions[*]}{.type}{"="}{.status}{" reason="}{.reason}{" message="}{.message}{"\n"}{end}'

#Resolution

Follow the most specific Pod event or Sandbox condition. Common causes include image pull failures, PodSecurity rejection, unavailable resources, invalid scheduling constraints, missing RuntimeClass, PVC provisioning, or blocked dependencies. Do not interpret the presence of the Suspended condition as suspended state; inspect its boolean status.

#Image Pull Fails

#Symptom

The managed Pod reports ErrImagePull or ImagePullBackOff.

#Checks

kubectl describe pod python-sandbox -n "$BUSINESS_NAMESPACE"
kubectl get events -n "$BUSINESS_NAMESPACE" --sort-by=.lastTimestamp

#Resolution

Verify the image registry, repository, tag, target-cluster network path, registry credentials, and ServiceAccount image pull configuration. Use a trusted image available to the workload cluster. Do not disable image verification controls to hide a registry or credential error.

#RBAC or ServiceAccount Is Insufficient

#Symptom

The API returns Forbidden, a client cannot create Sandbox resources, or kubectl exec is denied.

#Checks

kubectl auth can-i create sandboxes.agents.x-k8s.io \
  -n "$BUSINESS_NAMESPACE"

kubectl auth can-i create pods/exec \
  -n "$BUSINESS_NAMESPACE"

kubectl get serviceaccount,role,rolebinding \
  -n "$BUSINESS_NAMESPACE"

#Resolution

Grant only the required namespaced verbs through a dedicated Role and RoleBinding. Core-only users do not need extension-resource permissions. Do not grant cluster-admin and do not give business identities permission to edit CRDs or the controller Deployment.

#PodSecurity Rejects the Workload

#Symptom

Events report violates PodSecurity "restricted" or reject the generated Pod.

#Checks

kubectl describe sandbox python-sandbox -n "$BUSINESS_NAMESPACE"
kubectl get events -n "$BUSINESS_NAMESPACE" --sort-by=.lastTimestamp

#Resolution

Add a restricted-compatible security context: run as non-root, use an explicit non-root UID/GID when the image supports it, disable privilege escalation, drop all capabilities, and use RuntimeDefault seccomp. Fix the workload manifest instead of lowering the namespace Pod Security standard.

#NetworkPolicy Blocks DNS or the Target Service

#Symptom

The Sandbox is Ready, but DNS resolution or a required endpoint is unreachable.

#Checks

kubectl get networkpolicy -n "$BUSINESS_NAMESPACE"
kubectl describe networkpolicy -n "$BUSINESS_NAMESPACE"

kubectl exec -n "$BUSINESS_NAMESPACE" python-sandbox -c python -- \
  python -c 'import socket; print(socket.gethostbyname("kubernetes.default.svc"))'

#Resolution

Confirm that the policy selector matches the workload labels. Add explicit DNS access and the minimum required destination rules before tightening default deny. Verify that the cluster CNI enforces NetworkPolicy as expected. Do not replace reviewed destination rules with unrestricted 0.0.0.0/0 egress.

#shutdownTime Is Invalid or Already Expired

#Symptom

The resource is rejected, expires immediately, or does not expire at the expected time.

#Checks

kubectl get sandbox python-sandbox \
  -n "$BUSINESS_NAMESPACE" \
  -o jsonpath='{.spec.shutdownTime}{" policy="}{.spec.shutdownPolicy}{"\n"}'

#Resolution

Use an absolute RFC3339 timestamp with an explicit timezone, preferably UTC Z, and make sure it is in the future. Check shutdownPolicy. Activity does not renew shutdownTime; it is not an idle timeout.

#RuntimeClass Is Missing or Cannot Schedule

#Symptom

The API reports a missing RuntimeClass, or the Pod remains Pending after a RuntimeClass is selected.

#Checks

kubectl get runtimeclass
kubectl describe pod python-sandbox -n "$BUSINESS_NAMESPACE"
kubectl get nodes -o wide
kubectl get events -n "$BUSINESS_NAMESPACE" --sort-by=.lastTimestamp

#Resolution

Use a RuntimeClass that the cluster administrator has installed and validated. Confirm compatible nodes, runtime handlers, node labels, taints, tolerations, resource overhead, and hardware virtualization requirements. Agent Sandbox does not install Kata Containers or gVisor.

#Collect a Diagnostic Snapshot

When escalation is required, collect the resource state without including credentials or secret data:

kubectl get sandbox,sandboxclaim,sandboxwarmpool,sandboxtemplate \
  -A

kubectl describe sandbox python-sandbox \
  -n "$BUSINESS_NAMESPACE"

kubectl get pods -n "$BUSINESS_NAMESPACE" -o wide
kubectl get events -n "$BUSINESS_NAMESPACE" --sort-by=.lastTimestamp
kubectl logs deployment/agent-sandbox-controller \
  -n agent-sandbox-system \
  --tail=200

Do not delete CRDs during troubleshooting. CRD deletion removes the API definition and can delete every instance of that resource type across the cluster.