Teleport 官方 TBot Helm Chart 实战指南在 Kubernetes 中部署 Machine ID Agent【免费下载链接】teleportThe easiest, and most secure way to access and protect all of your infrastructure.项目地址: https://gitcode.com/gh_mirrors/tel/teleport导读TBot 是 Teleport Machine ID 的核心组件负责为工作负载签发短期身份凭据。Teleport 官方在仓库的examples/chart/tbot/目录中提供了 TBot Helm Chart用于将 Machine ID Agent 一键部署进 Kubernetes 集群使集群内运行的工作负载能够安全地加入 Teleport 集群并获取身份。本文以 TBot Chart README 为主体结合 Chart 的values.yaml、模板源码与 tbot 配置实现完整讲解该 Chart 的部署前提、最小化配置、深度定制、Argo CD 集成与底层原理读完即可上手部署并理解其工作机制。一、Chart 概览与适用场景TBot Chart 的目标非常明确在 Kubernetes 集群中部署一个 Machine ID Agenttbot实例让运行在 Kubernetes 中的工作负载能够向 Teleport 集群完成认证并获取身份凭据。从 Chart.yaml 可以看到该 Chart 的名称是tbot版本与appVersion同步当前仓库中为19.0.0-prealpha.2说明 Chart 与 tbot 镜像版本严格绑定——默认情况下安装哪个版本的 Chart就会运行哪个版本的 tbot。典型的适用场景包括Pod 需要访问受 Teleport 保护的 SSH/数据库/Kubernetes 资源需要在 Kubernetes 内为工作负载签发短期、自动轮换的证书需要将 Teleport 托管的 Kubernetes 集群同步到 Argo CDChart 内置argocd输出类型。官方 README 明确强调了一个设计取向默认使用kubernetes加入方式join method并且可以定制为任意受委托的 join method但不推荐使用tokenjoin method部署本 Chart——因为token属于静态凭据而 Kubernetes 部署场景理应优先使用基于 ServiceAccount 的委托认证。二、部署前置条件开始使用该 Chart 之前需要提前准备好三样信息对应 README 中的清单Teleport Proxy Service 或 Auth Service 的地址Teleport 集群名称——官方建议通过tctl status命令获取为 Machine ID 和你的 Kubernetes 集群配置的 join token 名称。其中第 3 项是安全配置的关键Teleport 侧的 join tokentbot角色需要允许kubernetes加入方式并对目标集群/命名空间/ServiceAccount 做限定。关于 join token 的完整定义与授权方式可参考 join-methods.mdx 中的 token 资源参考章节。三、快速开始最小化配置README 给出的最小化配置只需三个字段见 .lint/simple.yaml这也是 Chart 的 lint 示例clusterName: test.teleport.sh teleportProxyAddress: test.teleport.sh:443 token: my-token将该内容保存为values.yaml后执行安装helm install tbot ./examples/chart/tbot -f values.yaml安装完成后Chart 会在部署所在的命名空间中写入一个名为helm-release-name-out的 Kubernetes Secret例如tbot-out其中包含 tbot 生成的 Teleport identity 文件。工作负载只需读取该 Secret 即可获得集群身份。关于这份最小配置有三个值得注意的细节clusterName必须与 Teleport 集群名一致它同时被用作kubernetesjoin 时 ServiceAccount Token 的audience见 deployment.yaml 中的audience: {{ .Values.clusterName }}teleportProxyAddress必须携带端口号通常为443Teleport Cloud / Enterprise Cloud 必须通过 Proxy 连接或3080token字段默认值为 Helm release 名称见 values.yaml 与_helpers.tpl中的tbot.tokenName并且只有当joinMethod为token时才属于敏感信息——使用kubernetes等委托方式时它只是 token 名称。四、连接地址配置Proxy 还是 AuthChart 提供两种连接地址字段二者互斥模板_config.tpl中通过required强制校验字段说明典型值teleportProxyAddressProxy Service 地址必须含端口通常443或3080。最常用、推荐的方式Teleport EnterpriseCloud必须使用test.teleport.sh:443teleportAuthAddressAuth Service 地址必须含端口通常3025。仅当 tbot 与teleport-clusterHelm release 部署在同一 Kubernetes 集群、且能直接访问 Auth Service 时使用teleport-auth.teleport-namespace.svc.cluster.local:3025模板中的校验逻辑examples/chart/tbot/templates/_config.tpl两者都为空 → 报错teleportAuthAddress or teleportProxyAddress must be provided两者都设置 → 报错teleportAuthAddress and teleportProxyAddress are mutually exclusiveclusterName为空 → 报错clusterName must be provided。生成到 ConfigMap 的 tbot 配置中Proxy 地址映射为proxy_serverAuth 地址映射为auth_server配置结构为version: v2与 lib/tbot/config/config.go 中 tbot 配置解析模型一致。五、深度定制细粒度 values 与tbotConfigREADME 给出了两条定制路线并给出了明确建议细粒度 values使用 Chart 提供的具体配置项如defaultOutput、outputs、services、joinMethod等tbotConfig全量注入直接传入 tbot 的 YAML 配置注入到任意字段。推荐优先使用细粒度 values理由是这些字段会被 Chart 持续维护未来更新 Chart 时能更好地兼容受益而tbotConfig是逃生舱适合细粒度 values 无法覆盖的场景。5.1 合并机制与优先级两者并非互斥而是合并关系。在 config.yaml 中可以看到关键实现mustMergeOverwrite (include tbot.config . | fromYaml) .Values.tbotConfig | toYaml即Chart 生成的配置tbot.config模板输出先解析为 YAML再与tbotConfig深度合并tbotConfig中出现的字段以tbotConfig为准。注意合并而非覆盖整体tbotConfig只覆盖其显式声明的键Chart 生成的其余字段仍然保留。这一点在 tests/config_test.yaml 的 custom 快照测试中得到了验证——测试向tbotConfig注入xyzzy、yxzyy及自定义outputs同时保持基础配置不变。同时需要注意一旦设置了tbotConfig部分细粒度 values如teleportProxyAddress、joinMethod、outputs、services等会被忽略values.yaml 中逐一标注了 Ignored iftbotConfigis set因为定制意图已交给tbotConfig全权表达。5.2 细粒度配置项一览以下配置项均可通过--set或 values 文件使用完整默认值见 values.yaml配置组关键字段默认值 / 说明镜像image、imagePullPolicypublic.ecr.aws/gravitational/tbot-distroless、IfNotPresent集群连接clusterName、teleportProxyAddress、teleportAuthAddress均必填其一见上节加入方式joinMethod默认kubernetes可改为任意委托方式不推荐token加入令牌token默认取 Helm release 名默认输出defaultOutput.enabled默认true输出 identity 到release-outSecret扩展输出outputs与 tbot.yaml 的outputs字段同格式扩展服务services与 tbot.yaml 的services字段同格式持久化persistencesecret默认/disabledArgo CDargocd.*默认关闭详见第六节全量配置tbotConfig默认{}合并且优先运维anonymousTelemetry、debug、extraArgs、extraEnv默认关闭/空账号与 RBACserviceAccount.create/name、rbac.create默认均trueK8s 调度resources、affinity、tolerations、nodeSelector、imagePullSecrets默认空存储与卷extraVolumes、extraVolumeMounts默认空标签注解extraLabels.*、annotations.*按 Role/RoleBinding/ConfigMap/Deployment/Pod/ServiceAccount 细分安全上下文securityContext、podSecurityContext默认null不设置版本覆盖teleportVersionOverride默认空仅供开发调试5.3teleportVersionOverride的警告teleportVersionOverride用于覆盖 tbot 镜像版本但 values.yaml 给出了强烈警告它仅供开发调试使用绝不应用来控制生产部署中的 Teleport 版本。Chart 与特定 Teleport 版本绑定混用不同版本会带来兼容性问题。正确的版本管理方式是helm install --version X.Y.Z tbot ./examples/chart/tbot六、持久化模式persistencetbot 需要存储内部状态证书轮换、部署跟踪等Chart 通过persistence字段提供两种模式secret默认将 tbot 内部存储写入 Kubernetes Secret。模板生成storage: {type: kubernetes_secret, name: release名}disabled不持久化数据模板生成storage: {type: memory}。文档注明这可能影响跨生命周期追踪 bot 部署的能力。该字段在模板中做了严格校验其他取值会直接报错persistence must be secret or disabled。从源码侧看tbot 的存储本质是destination抽象config_storage.go 中StorageConfig默认落到本地目录defaults.DataDir/bot而在 Kubernetes 中则由 Chart 改写为kubernetes_secret类型。这也解释了为什么kubernetes_secret目标需要 Pod 拥有操作 Secrets 的权限——见第七节 RBAC 部分。七、Argo CD 集成Chart 原生支持将 Teleport 托管的 Kubernetes 集群同步到 Argo CD通过argocd配置组开启argocd: enabled: true clusterSelectors: - name: foo - labels: foo: bar secretNamespace: my-namespace project: my-argo-project namespaces: - dev - prod clusterResources: true完整示例见 .lint/argocd.yaml该文件同时是 Chart 的 lint/测试输入。argocd组支持以下字段字段作用enabled是否启用 Argo CD 输出启用时clusterSelectors必填clusterSelectors决定同步哪些 Kubernetes 集群可指定name或按labels匹配secretNamespace集群 Secret 写入的命名空间必须是 Argo CD 运行所在的命名空间默认当前命名空间secretNamePrefixSecret 名前缀默认teleport.argocd-clustersecretLabels/secretAnnotations应用到 Secret 的标签/注解值可以是 Go 模板字符串由 tbot 渲染而非 Helm支持{{.ClusterName}}、{{.KubeName}}、{{index .Labels key}}project关联的 Argo CD projectnamespaces允许集群操作的命名空间列表clusterResources是否允许操作集群级资源仅在namespaces非空时生效clusterNameTemplate集群在 Argo CD 中的命名模板默认{{.ClusterName}}-{{.KubeName}}在模板层argocd.enabled会生成类型为kubernetes/argo-cd的 tbot output见 _config.tpl将上述字段一一映射为selectors、secret_namespace、secret_labels、secret_annotations、project、namespaces、cluster_resources、cluster_name_template。注意启用 Argo CD 时默认 identity 输出依然存在二者可以共存。八、部署资源源码级剖析Chart 共渲染 5 类 Kubernetes 资源逐一分析其设计意图。8.1 ConfigMap配置的生成与校验config.yaml 生成名为release名的 ConfigMap其中tbot.yaml键存放最终合并后的配置。生成逻辑集中在 _config.tpl顶层version: v2tbot 配置 schema 版本proxy_server或auth_server二选一onboarding.join_method与onboarding.token对应源码 config.go 中的Onboarding结构storage按persistence生成outputs聚合默认 identity 输出、Argo CD 输出与自定义outputsservices透传自定义服务配置。8.2 Deployment单副本与探针deployment.yaml 中的设计要点replicas: 1strategy: Recreate模板注释明确指出在kubernetes_secret目标建立锁机制之前必须保持单副本并使用 Recreate 更新策略避免多副本同时写入同一 Secret 造成冲突配置变更自动重建Pod 注解携带checksum/config对 ConfigMap 内容做 sha256sum配置变化即触发滚动重建启动参数start -c /config/tbot.yaml --log-format json --diag-addr 0.0.0.0:3001debug时追加--debugextraArgs可追加任意参数关键环境变量POD_NAMESPACEkubernetes_secretdestination 正常工作所必需TELEPORT_NODE_NAMEWorkload Identity Kubernetes 工作负载证明attestation所需KUBERNETES_TOKEN_PATH/var/run/secrets/tokens/join-sa-tokenjoin 时使用的 ServiceAccount JWT 路径TELEPORT_ANONYMOUS_TELEMETRY1仅在anonymousTelemetry: true时注入诊断端口与探针容器暴露3001diagnosticslivenessProbe检查/livez初始 10s、每 10s、失败 6 次即 60s 后杀 PodreadinessProbe检查/readyz初始 5s、每 10s、失败 3 次标记未就绪join token 注入通过 projected volume 挂载 ServiceAccount TokenexpirationSeconds: 600Kubernetes 支持的最小值官方推荐audience设置为clusterName。8.3 ServiceAccount 与 RBAC最小权限模型serviceaccount.yaml默认创建名为 release 名的 ServiceAccount可通过serviceAccount.create/name关闭或改名role.yaml授予对secrets资源的*权限——注释明确说明这是kubernetes_secretdestination 正常工作的必要条件tbot 需要读写存储/输出 Secretrolebinding.yaml将上述 Role 绑定到 ServiceAccount。rbac.create: false时由使用者自行创建所需 RBAC 资源。九、Join Method 的底层支持面Chart 默认joinMethod: kubernetes。从源码 onboarding/config.go 看tbot 支持的加入方式全集包括azure、azure_devops、bitbucket、circleci、gcp、github、gitlab、iam、kubernetes、spacelift、token、tpm、terraform_cloud、oracle、bound_keypair、env0、generic_oidc。配置解析时config.go会校验join_method是否落在该集合内非法值直接报错。针对kubernetes方式join-methods.mdx 进一步说明存在三种变体In-cluster使用 Kubernetes TokenReview API 验证 Pod 身份仅适用于与 Auth Service 同集群运行的自托管 TeleportPod 进入Terminated状态后 token 立即失效可用性最好JWKS导出 Kubernetes 签名公钥验证 SA token 签名Auth Service 无需访问集群可用于任意集群含 Teleport CloudOIDC适用于使用公开 OIDC 发行者的集群Kubernetes 1.21 的 Service Account Issuer Discovery 特性。Chart 的 Deployment 通过 projected SA tokenaudience指向集群名为上述机制提供凭据来源。若改用其他委托方式如gcp、iam等只需修改joinMethod并确保 Pod 具备相应运行环境如工作负载身份无需改动其他配置。十、测试与贡献Chart 自带基于 helm-unittest 目录覆盖 ConfigMap、Deployment、Role、RoleBinding、ServiceAccount 五类资源并通过快照__snapshot__/锁定渲染结果。测试输入复用.lint/下的示例 valuessimple/full/argocd其中 .lint/full.yaml 是一个覆盖几乎所有可配置项的全家桶示例可作为编写真实 values 的参考模板。若要为本 Chart 贡献代码请先阅读 CONTRIBUTING.md其要求包括为新增 values 在.lint/下补充示例、在tests/下补充单测、更新values.schema.json校验、在 Helm 参考文档中记录变更并运行make lint-helm test-helm或通过make -C build.assets lint-helm test-helm在 Docker 中执行验证改动。结语Teleport 官方 TBot Helm Chart 的设计思路可以概括为默认安全、细粒度可配、必要时全量注入默认走kubernetes委托 join、默认输出 identity 到 Secret、默认创建最小权限 RBAC同时通过tbotConfig的深度合并机制为高级用户保留完全定制的入口。理解其 values 体系与模板渲染逻辑连接地址互斥校验、持久化类型映射、Argo CD 输出、探针与 join token 注入即可在 Kubernetes 上稳定、安全地运行 Machine ID 工作负载。【免费下载链接】teleportThe easiest, and most secure way to access and protect all of your infrastructure.项目地址: https://gitcode.com/gh_mirrors/tel/teleport创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考