OpenSandbox K8s日志体系与E2E排障指南：部署问题快速定位

OpenSandbox K8s日志体系与E2E排障指南部署问题快速定位【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox本文带你快速掌握OpenSandbox面向 AI Agent 的开源沙箱运行时在 Kubernetes 环境下的日志体系与 E2E 排障方法。OpenSandbox 的 K8s 控制器基于 zap 提供结构化 JSON 日志、自动轮转与压缩能力结合官方 E2E 排障文档和 CLI 诊断命令你可以在几分钟内定位部署失败、Pool 卡住、Pod 异常等常见问题。一、OpenSandbox 日志体系统一、结构化、可轮转OpenSandbox 各组件controller、execd、ingress 等共用同一套日志实现核心特性包括特性说明结构化输出默认 JSON 编码 ISO8601 时间戳方便日志系统采集日志级别debug / info / warn / error / fatal默认 info输出目标默认 stdout可通过环境变量OPENSANDBOX_LOG_OUTPUT指定文件路径支持逗号分隔多路输出自动轮转基于 lumberjack 实现默认单文件 100MB 轮转、保留 10 份、最长 30 天、gzip 压缩快速失败非法输出路径/无写权限会在启动时直接报错避免日志静默丢失实现代码见 zap.goRotateConfig定义了轮转参数rotateWriter为每个输出路径挂上 lumberjack 写入器。 排查技巧如果怀疑日志没写到文件先确认进程是否真的启动成功——OpenSandbox 会在构建日志器时校验输出路径权限不足会直接 panic 退出。二、Controller 日志配置5 个常用参数K8s Controller 除继承 zap 标准参数外还提供文件日志相关 flag详见 logging.md参数默认值作用--enable-file-logfalse开启文件输出--log-file-path/var/log/sandbox-controller/controller.log日志文件路径--log-max-size100单文件最大 MB 数--log-max-backups10保留旧文件数--log-max-age30保留天数--zap-encoder/--zap-log-leveljson / info编码格式与级别Helm 部署时这些参数通过 Deployment 的args注入模板参考 deployment.yaml完整部署流程见 HELM-DEPLOYMENT.md。排障时推荐组合临时开启--zap-log-leveldebug观察调度与分配细节生产环境保持--zap-encoderjson便于日志平台解析。三、E2E 测试失败三步快速定位OpenSandbox 的 E2E 测试分三类完整指南见 E2E-TROUBLESHOOTING.mdCore E2Ekubernetes/test/e2e/基于 Kind Ginkgo验证 Pool / BatchSandbox 调度Task-Executor E2Ekubernetes/test/e2e_task/验证任务执行与进程管理gVisor Runtime E2Ekubernetes/test/e2e_runtime/验证安全运行时第 1 步读失败断言E2E 使用 Ginkgo 框架Core E2E 在AfterEach中会自动收集现场controller Pod 日志、Kubernetes Events、Pod describe 输出。优先阅读这些自动采集信息而不是盲目重跑。第 2 步单条重跑失败用例# 只跑描述匹配的失败用例 make test-e2e-main GINKGO_ARGS-ginkgo.focusPool eviction第 3 步保留集群手工排查默认测试结束后 Kind 集群会被销毁。若需现场排查可手动建集群、部署 controller 并 apply 对应测试数据kind create cluster --name sandbox-k8s-test-e2e make install make deploy CONTROLLER_IMGyour-image kubectl apply -f test/e2e/testdata/pool-basic.yaml四、4 类高频部署问题与定位命令1️⃣ Controller Pod 未就绪Eventually(verifyControllerUp)超时通常源于镜像没 load 进 Kind 集群、拉取策略为IfNotPresent但镜像不存在、或资源不足被 OOMKilled。kubectl get pods -n opensandbox-system -l control-planecontroller-manager kubectl describe pod -n opensandbox-system -l control-planecontroller-manager kubectl logs -n opensandbox-system -l control-planecontroller-manager # 镜像未加载时 kind load docker-image image --name sandbox-k8s-test-e2e2️⃣ Pool Pod 卡在非 Runningkubectl describe pod查看事件常见状态ImagePullBackOff镜像地址错、Pending节点资源不足、CrashLoopBackOff容器启动失败。3️⃣ BatchSandbox 分配状态不符合预期检查alloc-statusannotation 与 Pool 的available字段并在 controller 日志中搜索schedule / allocate / insufficient关键字kubectl logs -n opensandbox-system -l control-planecontroller-manager \ | grep -i schedule\|allocate\|insufficient4️⃣ Eventually 超时但手工验证已通过多为最终一致性问题默认EventuallyTimeout只有 2 分钟Kind 集群性能有限或代码改了但镜像没重建。重建并重新加载镜像即可make docker-build-controller CONTROLLER_IMGcontroller:dev kind load docker-image controller:dev --name sandbox-k8s-test-e2e五、CLI 一键诊断DevOps Summary除了 kubectlOpenSandbox CLI 内置了 DevOps 诊断命令一次调用即可汇总inspect容器状态 events logs。对已创建沙箱执行osb devops summary sandbox-id输出如下输出继续展示环境变量、Events 与最近日志。图中OOMKilled事件直接暴露了容器因内存不足被杀的原因——这正是排障时最想要的答案命令实现位于 devops.pysummary子命令聚合 inspect、events、logs 三类信息独立查看日志可用osb diagnostics logs。六、Task-Executor 排障理解进程执行流Task-Executor E2E 若出现进程不可见或停止超时问题理解其 Host / Sidecar 两种模式的执行流程非常关键对照该流程图排查Sidecar 模式进程不可见确认--pidcontainer:指向目标容器、--enable-sidecar-modetrue已设置、--main-container-name与目标容器的SANDBOX_MAIN_CONTAINER环境变量一致Docker 容器启动失败用docker info检查环境清理上一次残留容器task-e2e-target/task-e2e-executorTask 状态异常直接curl http://localhost:5758/tasks查询任务状态并docker logs task-e2e-executor看执行器日志七、常用调试命令速查清单目的命令实时跟踪 controller 日志kubectl logs -n opensandbox-system -l control-planecontroller-manager -f查看全部沙箱资源kubectl get pools,batchsandboxes,pods -A查看 CRD 是否正确安装kubectl get crd pools.sandbox.opensandbox.io -o yaml校验 controller RBAC 权限kubectl auth can-i --assystem:serviceaccount:opensandbox-system:opensandbox-controller-manager create pods清理残留 Kind 集群kind get clusters→kind delete cluster --name name清理 Docker 资源docker system df→docker system prune -a总结日志是排障第一入口OpenSandbox 全组件统一 JSON 日志 自动轮转临时开--zap-log-leveldebug可看到调度分配全过程E2E 失败先读自动采集现场Ginkgo 的AfterEach已附带 Pod 日志、Events 与 describe再单条 focus 重跑CLI summary 一键定位osb devops summary能直接暴露 OOMKilled、端口、Label 等关键信息配合本文的 logging.md、E2E-TROUBLESHOOTING.md 与 HELM-DEPLOYMENT.md 三份官方文档你可以建立一套完整的 OpenSandbox K8s 部署问题快速定位工作流。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考