#常见问题

从平台生命周期的内层向外排查 Agent Sandbox：先检查 Cluster Plugin 状态、controller、API、Sandbox conditions、managed Pods，然后再检查 workload 依赖项。

在执行任何命令之前，请先确认当前活动的 cluster 和 namespace：

kubectl config current-context
export BUSINESS_NAMESPACE=agent-demo

在 global cluster 上运行 ModuleInfo 检查。在目标 workload cluster 上运行所有 controller、CRD、Sandbox、Pod、NetworkPolicy、RuntimeClass 和事件检查。

#ModuleInfo 未变为 Running

#症状

Cluster Plugin 的安装或升级一直处于 pending、failed，或者报告的版本与 v0.5.4-1 不同。

#检查

在 global cluster 上：

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

#解决方法

通过 ACP Cluster Plugin 工作流解决 ModuleInfo 或 AppRelease 生命周期错误。确认所选 package 为 v0.5.4-1，并且目标 workload cluster 可达。不要通过直接编辑 ModuleInfo、Helm release 或 controller Deployment 来绕过平台。

#Controller Deployment 未就绪

#症状

agent-sandbox-controller 存在不可用副本，或者其 rollout 超时。

#检查

在 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

#解决方法

使用 Pod 状态和事件来修正 image pull、资源、调度、安全性或配置错误。如果 node selector 或 toleration 导致 controller 无法调度，请使用 Update 更改 Cluster Plugin 设置，并等待新的 rollout。

#缺少 Core 或 Extension CRD

#症状

API server 针对 Sandbox 或 extension 资源返回 “the server doesn't have a resource type”。

#检查

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

#解决方法

确认 Cluster Plugin 安装已成功完成。通过 ACP 对安装进行 reconcile。不要在 ACP 管理的安装之上应用无关的 upstream manifest，也不要临时创建 CRD 版本。

#Extension CRD 存在，但资源未进行 reconcile

#症状

SandboxTemplate、SandboxWarmPool 或 SandboxClaim 对象已被接受，但状态没有变化。

#检查

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

#解决方法

controller 参数必须包含 --extensions=true。如果没有，请使用 Cluster Plugin Update 启用 extension controllers，并等待 rollout 完成。同时验证模板和 warm-pool 的引用名称以及所需的 NetworkPolicies。

#Sandbox 未就绪

#症状

Ready 等待超时，或者 Sandbox 报告 Ready=False 或 DependenciesNotReady。

#检查

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

检查所有 Sandbox conditions：

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

#解决方法

按照最具体的 Pod event 或 Sandbox condition 进行处理。常见原因包括 image pull 失败、PodSecurity 拒绝、资源不可用、调度约束无效、缺少 RuntimeClass、PVC provisioning，或依赖项被阻塞。不要将 Suspended condition 的存在理解为 suspended 状态；请检查其布尔状态。

#Image Pull 失败

#症状

managed Pod 报告 ErrImagePull 或 ImagePullBackOff。

#检查

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

#解决方法

验证 image registry、repository、tag、target-cluster 网络路径、registry 凭证以及 ServiceAccount 的 image pull 配置。使用 workload cluster 可访问的受信任 image。不要通过禁用 image 验证控制来掩盖 registry 或凭证错误。

#RBAC 或 ServiceAccount 权限不足

#症状

API 返回 Forbidden，客户端无法创建 Sandbox 资源，或者 kubectl exec 被拒绝。

#检查

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"

#解决方法

通过专用 Role 和 RoleBinding 仅授予所需的 namespaced verbs。仅有 core 权限的用户不需要 extension-resource 权限。不要授予 cluster-admin，也不要赋予业务身份编辑 CRD 或 controller Deployment 的权限。

#PodSecurity 拒绝 workload

#症状

事件报告 violates PodSecurity "restricted"，或者拒绝生成的 Pod。

#检查

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

#解决方法

添加与 restricted 兼容的安全上下文：以非 root 身份运行，在 image 支持时使用显式的非 root UID/GID，禁用 privilege escalation，丢弃所有 capabilities，并使用 RuntimeDefault seccomp。应修正 workload manifest，而不是降低 namespace 的 Pod Security standard。

#NetworkPolicy 阻止 DNS 或目标服务

#症状

Sandbox 已就绪，但 DNS 解析或所需 endpoint 无法访问。

#检查

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

#解决方法

确认 policy selector 与 workload labels 匹配。在收紧默认拒绝之前，添加显式的 DNS 访问和最低必需的 destination rules。验证 cluster CNI 是否按预期强制执行 NetworkPolicy。不要用不受限制的 0.0.0.0/0 egress 替换经过审核的 destination rules。

#shutdownTime 无效或已过期

#症状

资源被拒绝、立即过期，或者没有在预期时间过期。

#检查

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

#解决方法

使用带有显式时区的绝对 RFC3339 时间戳，最好使用 UTC Z，并确保其时间在未来。检查 shutdownPolicy。活动不会续期 shutdownTime；它不是 idle timeout。

#RuntimeClass 缺失或无法调度

#症状

API 报告缺少 RuntimeClass，或者在选择 RuntimeClass 后 Pod 仍然处于 Pending。

#检查

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

#解决方法

使用 cluster administrator 已安装并验证过的 RuntimeClass。确认兼容的节点、runtime handlers、node labels、taints、tolerations、资源开销以及硬件虚拟化要求。Agent Sandbox 不会安装 Kata Containers 或 gVisor。

#收集诊断快照

当需要升级处理时，请在不包含凭证或 secret 数据的情况下收集资源状态：

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

排查过程中不要删除 CRD。删除 CRD 会移除 API 定义，并可能删除整个 cluster 中该资源类型的所有实例。