Teleport Kubernetes Operator 贡献指南：从新增 CRD 到调试的完整实践

Teleport Kubernetes Operator 贡献指南从新增 CRD 到调试的完整实践【免费下载链接】teleportThe easiest, and most secure way to access and protect all of your infrastructure.项目地址: https://gitcode.com/gh_mirrors/tel/teleport本文基于 integrations/operator/CONTRIBUTING.md 展开面向希望为 Teleport Kubernetes Operator 增加新资源类型支持、运行集成测试并调试本地开发环境的开发者。读完本文你将掌握 CRD 生成、scheme 与 reconciler 编写、RBAC 配置的完整流程并能借助 k3d 与远程集群搭建可复现的本地调试环境。Teleport Kubernetes Operator 是一个基于 operator-sdk 的 Kubernetes Operator运行在进程内的 tbot 实例通过 MachineID 加入 Teleport 集群并利用 gRPC 客户端将 Kubernetes 自定义资源CR与 Teleport 资源进行双向调和reconcile。其架构细节可参考 integrations/operator/README.md其中包含完整的调和流程图创建/更新、删除、finalizer、所有权校验、scope 校验等。新增 Teleport 资源支持的完整工作流为 Operator 增加一种新的 Teleport 资源类型核心路径是CRD 生成 → Go 类型定义scheme→ reconciler 实现 → 注册 → RBAC 权限。整个流程中的构建目标集中在 integrations/operator/Makefile 中建议先通读该文件以理解各目标之间的依赖关系。第一步确保现有 CRD 已是最新状态在干净的仓库中、尚未做任何改动之前先运行make generategenerate目标由两部分组成参见 Makefile 中generate: generate-types crdgenerate-types调用controller-gen当前锁定版本为v0.20.0为apis/下的类型生成DeepCopy、DeepCopyInto、DeepCopyObject方法crd依次执行crd-docs与crd-manifests生成 CRD 清单与文档。如果此前用于生成 CRD 的.proto文件发生变化这一步会产生 diff。检查输出是否合理并提交相关变更确保后续工作建立在干净的基础上。第二步生成新的 CRD注册资源类型在 integrations/operator/crdgen/handlerequest.go 的resources列表中将新类型的名称加入generateSchema函数内的资源数组。该文件是整个 CRD 生成器的核心HandleCRDRequest与HandleDocsRequest分别处理 CRD 清单与文档输出generateSchema则遍历resources列表为每个资源调用generator.addResource并最终产出CustomResourceDefinition。列表中每种资源可以携带多个resourceSchemaOption常用选项包括withVersionOverride当类型名中不含版本号时强制指定版本例如LoginRule被显式覆盖为types.V1withNameOverride覆盖 Kubernetes Kind 名称例如ServerV2同时生成OpenSSHServer与OpenSSHEICEServer两个 KindwithAdditionalColumns为kubectl get增加自定义列如UserV2的 Roles 列、ProvisionTokenV2的 Join Method 与 System Roles 列withCustomSpecFields当 proto 消息没有独立spec字段时强制将根级字段纳入 CRD 的 spec如LoginRule的priority、traits_expression、traits_mapwithScope标记资源为 scoped 资源如ServerV2、Bot、AccessList、ScopedToken等withSingletonName单例资源如RetrievalModel使用types.MetaNameRetrievalModellegacyWithoutVersionInKindOverride兼容旧版本Kind 中不携带版本号。添加 proto 文件如果新资源的 proto 文件不在 integrations/operator/Makefile 的PROTOS列表中当前包含 loginrule、accesslist、legacy types、bot、workloadidentity、autoupdate、summarizer、accessmonitoringrules、scopes 等请将其加入。该列表同时驱动crd-manifests与crd-docs两个目标的protoc调用。运行差异检查make crd-manifests-diff该目标会用 crdgen 插件在临时目录重新渲染 CRD再与config/crd/bases目录逐文件diff。预期输出是新 CRD 文件或差异内容并以返回码 1 退出表示存在差异。仔细检查输出只应生成你新增的资源 CRD。如果其他 CRD 也被改动需要查明原因并针对受影响的资源规划额外测试或者撤销非本意修改。生成 CRD 与文档make crdcrd会调用crd-docs输出到docs/pages/reference/infrastructure-as-code/operator-resources/和crd-manifests输出到config/crd/bases并同步拷贝到examples/chart/teleport-cluster/charts/teleport-operator/operator-crds供 Helm chart 使用。再次运行差异检查make crd-manifests-diff此时应始终无差异、无错误退出。第三步创建与 CRD 匹配的 Go 类型scheme在apis/resources/version目录下为新资源添加类型定义。参考该目录下既有类型的写法例如 integrations/operator/apis/resources/v1/groupversion_info.go 与各类*_types.go文件。当前仓库中已有 v1、v2、v3、v5 四个版本目录分别承载不同类型的资源。若当前版本目录尚不存在需新建并必须从既有版本目录复制一份groupversion_info.go将版本号改为正确值不要遗漏//kubebuilder注释如//kubebuilder:object:roottrue、//kubebuilder:subresource:status等这些是 controller-gen 生成 DeepCopy 方法与 CRD 结构的关键标记添加资源后运行make generate生成DeepCopy*方法产物会落到各版本的zz_generated.deepcopy.go中。第四步创建新资源类型的 reconciler在 integrations/operator/controllers/resources 下创建 reconciler。优先复用泛型的TeleportResourceReconciler此时只需为新资源实现 CRUD 方法即可无需编写完整调和循环。泛型 reconciler 的底层实现在 integrations/operator/controllers/reconcilers/generic.goresourceClient[T]接口定义了Get、Create、Update、Delete四个 CRUD 方法实现该接口即可接入通用调和流程可选实现resourceMutator[T]接口Mutate(ctx, new, existing, crKey)在创建前或基于现有资源更新前对资源做修改Reconcile方法实现标准流程读取 CR → 检查teleport.dev/ignore注解 → 删除事件走 finalizerresources.teleport.dev/deletion→ 添加 finalizer → 调用Upsert调和Upsert内部会执行结构校验、scope 校验checkScope、所有权校验checkOwnership基于kubernetesOrigin 标签与 operator ID 标签并通过status.conditions报告每一步的结果Delete会先校验 scope 与所有权仅删除确由本 operator 管理的资源避免误删其他来源的资源。编写单元测试时尽量使用测试库 integrations/operator/controllers/resources/testlib 中提供的泛型测试辅助函数获取基线覆盖ResourceCreationTest验证资源创建路径ResourceDeletionDriftTest验证删除与漂移场景ResourceUpdateTest验证更新路径。此外在controllers/resources/testlib/env.go的defaultTeleportServiceConfig函数中为默认的 Teleport 角色补充新资源所需的权限该函数构建测试用 Teleport 实例并为其配置 operator 角色。第五步注册 reconciler 与 scheme在 integrations/operator/controllers/resources/setup.go 中实例化你的 controller并加入supportedReconcilers列表一个ReconcilerFactory切片每个工厂函数接收 Kube client、Teleport client 与OperatorMetadata仿照既有资源调用 reconciler 的SetupWithManager(mgr)方法将控制器注册到 controller-runtime manager。SetupAllControllers在启动时会通过filterEnabledReconcilers对每个候选 reconciler 做三重过滤CRD 是否已部署通过 Discovery API 查询gvkCache做了按 GroupVersion 的惰性缓存支持新版 operator 运行在旧 CRD 集群上的场景scoped 模式operator 处于 scoped 模式时跳过非 scoped 的 reconciler集群特性通过CheckFeatures检查 Teleport 集群广播的特性如 OSS 集群上不启动企业版资源的 reconciler。若新增了apis/resources/下的新版本目录还需要确保该版本的 scheme 被注册到根scheme在init()函数中调用类似resourcesvX.AddToScheme(scheme)的代码。第六步为新资源类型添加 RBAC 权限Operator 需要同时具备 Kubernetes 侧与 Teleport 侧的访问权限需修改三处Kubernetes RBACexamples/chart/teleport-cluster/charts/teleport-operator/templates/role.yaml —— 授予 operator 访问新 Kubernetes 资源的权限Teleport RBACexamples/chart/teleport-cluster/templates/auth/config.yaml —— 授予 operator 访问对应 Teleport 资源的权限调试角色integrations/operator/hack/fixture-operator-role.yaml —— 更新调试用 operator 角色的权限。调试角色是后续本地调试的基础fixture-operator-role.yaml定义名为operator的 Teleport 角色允许对role、user、auth_connector、lock、token、access_list、node、trusted_cluster、bot、workload_identity、app、db等资源执行增删改查integrations/operator/hack/fixture-operator-bot.yaml 则创建bot-operator角色与用户通过impersonate.roles: [operator]让 bot 以 operator 身份工作这是 MachineID bot 的典型最小权限模式。测试策略使用 k3d 与已发布 Teleport 镜像快速测试前提条件已安装 k3dDocker 处于运行状态。操作步骤# 创建 k3d 集群 k3d cluster create k3s-default # 构建 operator 并部署整套环境 make k3d-deploymake k3d-deploy的默认行为见 integrations/operator/Makefile默认使用已发布的镜像TELEPORT_IMAGE_DEFAULT : public.ecr.aws/gravitational/teleport-distroless与TELEPORT_IMAGE_VERSION ? 18.8.1构建 operator 镜像后通过k3d image import导入集群用 Helm 在test命名空间部署teleport-clusterchartoperator.enabledtrue、clusterNametest设置TELEPORT_UNSTABLE_SCOPESyes环境变量启用 scoped 资源支持可以通过追加--set extraEnv[N].name...的方式注入额外的特性开关。使用本地 Teleport 构建测试当需要验证未发布功能或 feature-flag 变更时通过覆盖TELEPORT_IMAGE与TELEPORT_IMAGE_VERSION切换到本地构建。Makefile 会自动检测当TELEPORT_IMAGE与默认 registry 镜像不同时即视为本地构建并将本地镜像导入 k3d。构建 Teleport 镜像在仓库根目录执行会在 Docker buildbox 内编译全部二进制并产出本地镜像# 仓库根目录 make image产物形如teleport:19.0.0-dev-arm64架构后缀随本机GOARCH变化。如果本地存在e/目录企业版代码部署 Teleport Pod 时通常还需要附带 license。本地镜像构建排障构建缓存异常时执行docker builder prune -af清理缓存buildbox 过期如 Go/Rust 版本不匹配时先重建 buildboxmake -C build.assets buildbox-centos7确保e的 ref 是最新的OSS 中已移除的内容可能在e/中仍有引用遇到 Rust 相关问题可执行rustup override unset或运行make ensure-wasm-bindgen FORCEtrue。创建 k3d 集群若尚未创建k3d cluster create k3s-default使用本地镜像部署企业版构建需先创建 license secretexport KUBECONFIG$(k3d kubeconfig write k3s-default) kubectl create namespace test kubectl -n test create secret generic license \ --from-filelicense.pemyour-path-to-license-file然后执行部署注意在integrations/operator目录下运行cd integrations/operator # 企业版本地构建同时设置 ENTERPRISE1 make k3d-deploy \ ENTERPRISE1 \ TELEPORT_IMAGEteleport \ TELEPORT_IMAGE_VERSION19.0.0-dev-arm64设置ENTERPRISE1后部署流程会额外把 license secret 注入test命名空间并在 Helm 中开启enterprisetrue与enterpriseImage。调试技巧在单元测试中调试设置环境变量OPERATOR_TEST_TELEPORT_ADDR后controller 测试将不再创建临时 Teleport 实例而是连接一个真实运行中的 Teleport 集群。测试使用本地tsh凭据进行认证因此请确保当前登录用户具备足够权限测试中的 operator 会以该用户身份对资源执行 CRUD。针对远程 Kubernetes 与 Teleport 集群调试Operator 天然支持同时对接远程的 Kubernetes 集群与 Teleport 集群。你需要一个已安装 CRD 的 Kubernetes 集群一个 Teleport 集群。搭建步骤部署 CRD若集群中尚未安装 CRD通过 Helm 安装--set enabledfalse表示不部署 operator 本身仅安装 CRDhelm install crds ../../examples/chart/teleport-cluster/charts/teleport-operator/ --set enabledfalse --set installCRDsalways代理 Kube API参照 kube-agent-updater 的 DEBUG 指南以你自己身份打开通往 Kube API 的代理即让 operator 进程以你的身份鉴权访问 Kube API。创建 Teleport operator 角色tctl create -f ./hack/fixture-operator-role.yaml即 integrations/operator/hack/fixture-operator-role.yaml该角色授予 operator 对各类 Teleport 资源的管理权限。创建 Teleport bot 角色与用户tctl create -f ./hack/fixture-operator-bot.yaml即 integrations/operator/hack/fixture-operator-bot.yaml内含bot-operator角色与用户角色通过impersonate获得operator角色的权限并只读访问cert_authority。创建 Teleport bot tokentctl create -f ./hack/fixture-operator-token.yaml警告该静态 token 在首次使用后即被消耗。若重启 operator必须重新创建 token并删除 bot 用户上的证书生成标签。此 join 方式仅适用于开发调试严禁在生产环境使用。运行 operator例如make build ./bin/manager \ -join-method token \ -token operator-token \ -auth-server TELEPORT_ADDR \ -kubeconfig PATH_TO_TEMP_KUBECONFIG \ -namespace NAMESPACE_WHERE_CRS_ARE其中make build由 integrations/operator/Makefile 定义会先执行generate再用go build -trimpath产出bin/manager二进制编译入口为 integrations/operator/main.gooperator 启动时先初始化日志再绑定operatorConfig与embeddedtbot.BotConfig的命令行参数-join-method token与-token operator-token指定 operator bot 的 join 方式仅限调试的静态 token-auth-server指向 Teleport 集群地址-kubeconfig指向临时 Kubeconfig即第 2 步代理生成的凭证文件-namespace指定 CR 所在的命名空间。至此一次完整的新增资源 → 生成 CRD → 实现 reconciler → 注册 → 配权限 → 测试 → 调试的 Operator 开发闭环即可跑通。理解 controllers/reconcilers/generic.go 中的泛型调和循环finalizer 管理、所有权与 scope 校验、状态上报是后续为任意新资源类型编写 controller 的关键基础。【免费下载链接】teleportThe easiest, and most secure way to access and protect all of your infrastructure.项目地址: https://gitcode.com/gh_mirrors/tel/teleport创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考