Teleport kube-agent-updater 本地调试指南通过 kubectl proxy 对接远端 Kubernetes 集群【免费下载链接】teleportThe easiest, and most secure way to access and protect all of your infrastructure.项目地址: https://gitcode.com/gh_mirrors/tel/teleport本文是 Teleport 仓库中integrations/kube-agent-updater组件下文简称 kube-agent-updater的调试实战指南。该控制器负责自动升级运行在 Kubernetes 集群内的 Teleport Agent如 teleport-kube-agent Helm chart 部署的实例在大规模集群中可以显著降低人工升级所有 Agent 的成本。读完本文你将掌握如何在本地机器上运行该控制器、通过 kubectl proxy 让本地进程直连远端 API Server并借助调试器排查本地环境正常但集群内运行异常的复杂问题。调试思路为什么要在本地运行控制器kube-agent-updater 本质上是一个基于 controller-runtime 实现的 Kubernetes 控制器。正常情况下它以 Deployment 或 StatefulSet 的形式运行在集群内部由集群统一调度。但集群内运行环境存在两个调试痛点容器日志分散、不易流式查看无法直接在进程上附加调试器如 delve、IDE 断点。DEBUG.md提供的思路非常直接在本地机器上直接运行控制器的二进制同时让它通过kubectl proxy与远端真实集群通信。这样既保留了真实集群环境真实的 API Server、真实的 Deployment/StatefulSet 资源、真实的镜像仓库签名校验又能获得本地进程的全部调试能力适合复现大多数复杂问题并针对特定场景做针对性排查。前提确认 kubectl 上下文可用在开始之前先确认当前 kubectl 配置能够正常访问目标集群kubectl cluster-info该命令会输出集群 API Server 地址与版本信息。如果这里就报错权限、网络、context 配置问题请先修复集群访问否则后续所有步骤都无法进行。这一步同时验证了你后续将要连接的远端集群身份正确。开启 API Server 代理接下来在一个终端中启动 kubectl 内置的 HTTP 代理将远端 API Server 暴露到本地端口kubectl proxykubectl proxy默认监听127.0.0.1:8001并把对该地址的请求转发到当前 context 指向的 API Server同时自动完成认证信息注入。保持这个终端持续运行不要关闭它——本地控制器进程将依赖这个代理通道。该代理只监听回环地址不会向局域网或公网暴露集群 API安全上可以放心同时它会在转发时自动处理当前 kubeconfig 中的凭证与 TLS 校验无需额外配置证书。构造临时 kubeconfig让控制器以为自己在集群内控制器通过标准 client-go / controller-runtime 机制加载 kubeconfig。为了让本地进程只通过本地代理访问集群需要为它准备一份全新的、临时的 kubeconfig而不是直接复用你日常使用的配置文件避免本地进程意外使用到你环境里的其他凭据或 Server 地址。打开第二个终端依次执行export KUBECONFIG$(mktemp) kubectl config set-credentials myself --usernamefoo kubectl config set-cluster local-server --serverhttp://localhost:8001 kubectl config set-context default-context --clusterlocal-server --usermyself kubectl config use-context default-context echo $KUBECONFIG逐条解释这条命令链的作用命令作用export KUBECONFIG$(mktemp)生成一个空临时文件作为新的 kubeconfig 路径并把该路径导出到当前 shell 环境变量。临时文件路径可通过最后的echo确认便于调试后清理kubectl config set-credentials myself --usernamefoo向该 kubeconfig 写入一个名为myself的用户凭据。代理会忽略明文用户名/密码这里只需满足 kubeconfig 语法合法即可kubectl config set-cluster local-server --serverhttp://localhost:8001声明集群端点指向本机kubectl proxy的地址。注意这里是http://而非https://因为代理本身是明文 HTTP 服务kubectl config set-context default-context --clusterlocal-server --usermyself把上述 cluster 与 user 组合成一个名为default-context的上下文kubectl config use-context default-context将新上下文设为当前默认上下文echo $KUBECONFIG打印临时 kubeconfig 文件路径方便后续引用或删除至此任何在此 shell 中启动的进程只要遵守KUBECONFIG环境变量约定就会把 API 请求发往http://localhost:8001即经由kubectl proxy直达远端集群。启动控制器设置 KUBECONFIG 环境变量并运行在同一个 shell即上面设置了KUBECONFIG的那个终端中运行 kube-agent-updater 控制器。控制器入口位于 integrations/kube-agent-updater/cmd/teleport-kube-agent-updater/main.go二进制或go run方式均可KUBECONFIG$KUBECONFIG go run ./integrations/kube-agent-updater/cmd/teleport-kube-agent-updater \ --agent-name你的 Agent Deployment/StatefulSet 名称 \ --agent-namespaceAgent 所在命名空间 \ --disable-leader-election \ --version-serverhttps://updates.releases.teleport.dev/v1/ \ --log-levelDEBUG对照源码以下是本地调试时最需要关注的启动参数--agent-name/--agent-namespace必填指定要更新的 Agent 工作负载名称与命名空间。源码中二者为空会直接报错退出见 main.go。--disable-leader-election本地调试强烈建议控制器默认启用 Leader Election源码见 main.go在本地调试时没有副本竞争且 Leader Election 依赖对 Lease 资源的写入显式关闭可以避免干扰。源码注释也明确说明该参数用于在 Kubernetes 之外运行的场景。--version-server或--proxy-address至少提供其一控制器需要上游来源获取目标版本与维护窗口信息。源码中两者均为空会直接报错退出见 main.go。默认版本服务器为https://updates.releases.teleport.dev/v1/通道默认为stable/cloud若你的场景由 Teleport Proxy 驱动RFD-184 模式则改用--proxy-address。--log-levelDEBUG默认日志级别为 INFO。调试阶段建议调成 DEBUG源码中控制器大量关键决策点如维护窗口判定、版本候选、镜像校验结果都以 V(1) 级别的调试日志输出见 pkg/controller/updater.go。其余常用参数还包括--base-image默认public.ecr.aws/gravitational/teleport、--pull-credentials取值有 docker / google / amazon / none、--update-group、--sync-period默认 10 小时等完整列表见 main.go。由于本地进程直接与真实集群交互务必确认--agent-name/--agent-namespace指向的是测试集群或可接受自动更新的目标工作负载避免控制器对生产 Agent 发起意外升级。从源码理解控制器在调试时做什么把控制器跑起来之后了解它内部的工作流能帮你更快定位问题。核心逻辑位于 pkg/controller/updater.go 的GetVersion方法它严格按以下顺序执行每步失败都会直接返回、不继续维护窗口判定maintenanceTriggers.CanStart()检查当前是否处于允许维护的时机包括关键更新failover 到 critical 触发器、工作负载健康检查、计划内维护窗口见 main.go。若未触发返回MaintenanceNotTriggeredError控制器只记录未触发维护不更新并定时重试。获取目标版本通过 version getterversion server 或 proxy拿到最新版本候选。版本变更合法性校验version.ValidVersionChange对比当前版本与目标版本判断变更是否合法如不允许降级。合法则用 base image 拼接出带 tag 的镜像候选。镜像签名校验imageValidators.Validate校验候选镜像的 cosign 签名生产构建默认信任teleportProdOCIPubKey预发布版本额外信任 staging 公钥校验通过才返回带 digest 的镜像引用最终写入工作负载的 PodSpec。如果调试目标是为什么没升级对照上述四步逐项查看 DEBUG 日志即可快速定位卡在哪一步如果目标是为什么升级失败重点看镜像签名校验相关错误源码中该分支会被记录为 error 级别日志见 pkg/controller/deployment.go。调试辅助技巧暂停/恢复更新对目标 Deployment 或 StatefulSet 打上teleport.dev/skipreconcile: true注解即可暂停控制器对该资源的协调实现见 pkg/controller/utils.go置为false或删除注解即可恢复。排查问题时先暂停、再逐步放开能显著降低干扰。查看状态 ConfigMap控制器会把最近一次更新结果版本、成功/失败、时间戳写入工作负载名-updater的 ConfigMap实现见 pkg/controller/status_writer.go。用kubectl get configmap agent-name-updater -n namespace -o yaml即可查看其内部agent.update.config字段中的status.lastUpdate这是判断上次更新是否成功最直接的手段。健康检查端点控制器默认在:8081暴露/healthz与/readyz本地调试时可用curl localhost:8081/healthz确认进程状态见 main.go。运行单元测试本地修改代码后可在 integrations/kube-agent-updater 目录通过make test运行测试含 controller、img、maintenance、podutils 等包的用例测试输出与日志会写入./test-logs目录见 Makefile。调试完成后调试结束别忘了关闭运行中的控制器进程CtrlC关闭kubectl proxy终端删除临时 kubeconfig 文件$KUBECONFIG指向的临时文件若调试过程中设置了teleport.dev/skipreconcile注解记得清理或复位。整个调试链路的关键在于本地二进制 远端真实集群 可注入的临时 kubeconfig。这套组合既能让你在熟悉的本地环境中使用调试器又不会与日常开发用的 kubeconfig 互相污染是排查 kube-agent-updater 复杂问题的高效路径。【免费下载链接】teleportThe easiest, and most secure way to access and protect all of your infrastructure.项目地址: https://gitcode.com/gh_mirrors/tel/teleport创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考