网络安全认证鉴权运维后端【免费下载链接】teleportThe easiest, and most secure way to access and protect all of your infrastructure.项目地址https://gitcode.com/gh_mirrors/tel/teleport点击查看免费下载导读本文聚焦于 Teleport 开源仓库中 Terraform Provider 文档体系 的构建与维护方式如何通过一条make docs命令从 proto 定义生成 Terraform Schema再借助定制的tfplugindocs工具渲染出覆盖全部资源的参考文档。读完本文你将掌握 Teleport Terraform Provider 文档的完整生成链路、默认模板与资源级模板的覆盖机制、tffile代码示例内嵌函数的使用方法以及如何为新增资源接入文档流水线。一、文档体系概览三类文档各司其职Teleport Terraform Provider 的文档并非单一文件而是由三类定位不同的文档构成分别面向查参数装环境上手用三种诉求文档类型定位适用场景Provider 参考reference描述每一个资源resource和数据源data source及其支持的字段编写.tf时查询属性、类型、是否可导入安装指南installation guide讲解如何安装、初始化 Provider 并与 Teleport 集群建立连接首次配置环境入门指南getting started以用 Terraform 配置用户和角色为典型场景的实操教程快速上手管理配置这三类文档在仓库中的落地形态并不相同参考类文档由自动化流水线生成详见下文第二、三节而安装与入门类文档则由人工撰写维护。参考文档的内容源头只有一个——Provider 自身的 Schema因此文档与代码永远一致是这套体系的设计目标这也解释了为什么构建文档必须先构建并安装 Provider。二、文档构建链路一条make docs做了什么在 integrations/terraform/Makefile 中文档目标被定义为.PHONY: docs docs: gen-tfschema install fmt ./gen/docs.sh $(VERSION)可见make docs是一条完整依赖链实际执行了四个阶段gen-tfschema重新从api/proto下的.proto定义生成 Terraform Schema 代码types_tfschema.go并重新生成 Provider 代码install在本地构建并安装 Provider 二进制供 Terraform CLI 调用fmt对示例目录执行terraform fmt -no-color -recursive格式化./gen/docs.sh $(VERSION)调用文档渲染脚本导出 Schema 并生成全部 Markdown/MDX 文件。也就是说make docs并不是一个独立的写文档动作而是重编译 Provider → 重新导出 Schema → 重新渲染文档的闭环。只要 proto 或 Provider 代码有变更执行make docs就能让参考文档同步更新避免手写文档与代码漂移。gen-tfschema从 proto 到 Schemagen-tfschema 目标依赖仓库自研的 protoc 插件protoc-gen-terraform调用脚本为 protoc-gen-terraform.sh针对每一个资源类型执行protoc \ -I../../api/proto \ -I$(PROTOBUF_MOD_PATH) \ --plugin$(PROTOC_GEN_TERRAFORM) \ --terraform_outconfigprotoc-gen-terraform-teleport.yaml:./tfschema \ teleport/legacy/types/types.proto从源码结构看每一个资源族都配有独立的生成配置YAML例如protoc-gen-terraform-accesslist.yaml、protoc-gen-terraform-loginrule.yaml、protoc-gen-terraform-scopedrole.yaml等对应api/proto/teleport下的accesslist/v1、loginrule/v1、scopes/access/v1等 proto 包。生成结果落在tfschema/目录随后由go run ./gen/main.go见 gen/main.go汇总并产出 Provider 代码。三、参考文档渲染脚本gen/docs.sh逐步拆解文档生成的核心逻辑在 gen/docs.sh脚本接收一个版本号参数完整流程如下1. 导出 Provider Schema脚本会在临时目录中写入一个最小化的main.tf声明所需 Provider 版本terraform { required_providers { teleport { source terraform.releases.teleport.dev/gravitational/teleport version $VERSION } } }然后依次执行terraform init与terraform providers schema -json schema.json得到全量 Schema 的 JSON 快照。这一步的意义在于文档字段永远来自真实编译出的 Provider而不是人工维护的清单。2. 调用定制的 tfplugindocs脚本使用了一个定制版tfplugindocsHashiCorp 官方terraform-plugin-docs的 fork关键调用参数如下go tool github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate \ --providers-schema $TMPDIR/schema.json \ --provider-name terraform.releases.teleport.dev/gravitational/teleport \ --rendered-provider-name teleport \ --rendered-website-dir$TMPDIR/docs \ --website-source-dir$TFDIR/templates \ --provider-dir $TFDIR \ --examples-dir$TFDIR/examples \ --website-temp-dir$TMPDIR/temp \ --hidden-attributesid,kind,metadata.namespace,metadata.revision其中值得注意的细节--website-source-dir指向integrations/terraform/templates即渲染所用的全部模板--examples-dir指向integrations/terraform/examples模板中引用的示例文件从这里读取--hidden-attributes将id、kind、metadata.namespace、metadata.revision等内部字段从文档中隐藏避免用户误用。定制版tfplugindocs之所以存在是因为 Teleport 的文档引擎要求输出与标准 Markdown 兼容的格式并能支持下文提到的tffile内嵌函数与 Tabs 组件。3. 格式转换与落盘渲染完成后脚本将所有.md重命名为.mdx并把resources-index、data-sources-index两个索引文件改名为resources/resources.mdx与data-sources/data-sources.mdx最后整体拷贝到仓库文档目录docs/pages/reference/infrastructure-as-code/terraform-provider/该目录在生成前会被整体清理。这意味着任何对参考文档的手工修改都会在下一次make docs时被覆盖。若需要为某个资源补充自定义说明正确姿势是使用资源级模板覆盖机制见第五节而不是直接编辑生成的文档。四、默认模板体系每个资源如何被渲染make docs的渲染基础是 templates 目录下的五类模板模板文件作用resources.md.tmpl单个资源参考页的默认模板data-sources.md.tmpl单个数据源参考页的默认模板index.md.tmplProvider 总览页最终落盘为terraform-provider.mdxresources-index.mdx.tmpl资源索引页data-sources-index.mdx.tmpl数据源索引页以资源页默认模板 resources.md.tmpl 为例其渲染结构为Front matter从资源名自动生成title、sidebar_label、description其中sidebar_label会自动剥离teleport_前缀自动生成声明模板内嵌Auto-generated file. Do not edit.与To regenerate, navigate to integrations/terraform and run make docs注释自定义引言若存在examples/resources/teleport_resource-name/introduction.md文件则通过includefileifexists函数将其内容引入页面顶部Schema 描述输出.Description示例区块若资源存在示例文件{{ if .HasExample }}渲染## Example Usage并通过{{tffile .ExampleFile }}内嵌示例代码Schema 字段表格由.SchemaMarkdown输出Import 区块若资源支持导入.HasImport使用{{codefile shell .ImportFile }}引入导入命令示例。这套模板设计保证了字段表格自动生成、示例自动发现、导入语法自动附带三个特性对全部资源开箱即用。五、为资源定制参考文档模板覆盖与tffile默认示例文件的自动发现默认模板会尝试引入名为examples/resources/teleport_resource-name/resource.tf的示例文件。也就是说只要你在examples/resources/下按约定命名目录示例就会自动出现在该资源的参考页上无需修改任何模板或脚本。资源级模板覆盖当你想为某个资源补充自定义说明、多段示例或进阶用法时可以复制默认模板为资源专属模板mkdir -p templates/resources cp templates/resources.md.tmpl templates/resources/resource_name.md.tmpl随后编辑该资源专属模板加入自定义文案与更多示例。渲染器会优先使用资源专属模板templates/resources/resource_name.md.tmpl找不到时才回退到默认模板。使用tffile内嵌多段代码示例文档模板中可用tffile函数按路径引入.tf示例文件配合文档引擎的 Tabs 组件可以为同一资源提供多套配置视角。原文档给出的典型写法以 provision token 为例## Example Usage Tabs TabItem labelsecret token This is a secret provision token. {{tffile ./examples/resources/teleport_provision_token/resource.tf }} /TabItem TabItem labeliam token This is an IAM token: {{tffile ./examples/resources/teleport_provision_token/iam.tf }} /TabItem /Tabs这种方式既保证了示例代码与仓库中可实际运行的examples/目录保持单一事实来源single source of truth又能在文档页面上呈现结构化的多 Tab 展示。与此配套resources.md.tmpl 中还用{{codefile shell .ImportFile }}渲染 shell 类型的导入命令块。六、新增一个资源文档如何自动跟上根据原文档的说明新增资源时无需手工编写参考文档——make docs会自动完成三件事从对应.proto文件及独立的protoc-gen-terraform-资源.yaml配置生成 Schema在资源索引页resources-index.mdx.tmpl渲染产物中自动加入新条目若检测到examples/resources/teleport_新资源名/resource.tf自动在参考页内嵌示例。因此贡献者的标准动作是定义/修改 proto → 补充examples/resources/下的示例文件可选introduction.md→ 运行make docs验证渲染结果。若需要额外说明再按第五节的方式创建资源级模板。七、本地开发与验证闭环在本地为文档改动做验证通常遵循 README.md 中给出的开发流程cd integrations/terraform make install # 本地构建并安装 Provider make test # 运行 Provider 单元/集成测试 make docs # 重新渲染参考文档其中make test会校验本机 Terraform 版本要求 v1.4测试日志输出到test-logs/目录见 Makefile。如需在真实集群上验证示例资源可依次执行teleport start # 启动本地 Teleport tctl create example/terraform.yaml # 创建 Terraform 用户与角色 tctl auth sign --formatfile --userterraform --out/tmp/terraform-identity --ttl10h make apply # terraform init apply -auto-approve make reapply # 修改 .tf 后再次 apply make destroy # 清理资源对应的 Provider 连接配置可参考 examples/provider/provider.tfterraform { required_providers { teleport { source terraform.releases.teleport.dev/gravitational/teleport version ~ 15.0 } } } provider teleport { # Update addr to point to Teleport Auth/Proxy # addr auth.example.com:3025 addr proxy.example.com:443 identity_file_path terraform-identity/identity }需要注意的是make docs的输出目录docs/pages/reference/infrastructure-as-code/terraform-provider/在每次生成前会被整体重建因此不要手工修改生成产物所有定制都应落在模板templates/与示例examples/层面。八、维护文档的最佳实践小结综合原文档与仓库实现Teleport Terraform Provider 文档维护可归纳为三条原则一切以 Schema 为准字段表格由terraform providers schema -json导出后渲染人工无需也无法维护字段清单模板与示例是唯二定制入口自定义文案进templates/resources/资源名.md.tmpl代码示例进examples/resources/teleport_资源名/生成产物一律视为只读文档随代码同生共死新增或修改资源后必须重跑make docs否则参考文档与 Provider 行为将不一致。理解这套代码 → Schema → 模板 → 文档的流水线你既可以作为使用者快速定位任意资源的字段与示例也可以作为贡献者规范地为新资源补齐高质量文档。赞分享网络安全认证鉴权运维后端【免费下载链接】teleportThe easiest, and most secure way to access and protect all of your infrastructure.项目地址https://gitcode.com/gh_mirrors/tel/teleport点击查看免费下载相关推荐Buttercup文档体系自动化API文档生成与维护Buttercup文档体系自动化API文档生成与维护 概述 在当今快速迭代的软件开发环境中API文档的准确性和时效性至关重要。Buttercup作为DARP终极指南如何利用Vimium打造高效浏览器导航体验终极指南如何利用Vimium打造高效浏览器导航体验 Vimium是一款浏览器扩展它以Vim编辑器的精神提供基于键盘的网页导航和控制功能让你无需鼠标即可高效开发工具FindMy.py文档体系自动生成与手动维护结合FindMy.py文档体系自动生成与手动维护结合 你是否在维护开源项目文档时遇到过这些困扰API变更后文档未能同步更新、手动编写重复内容效率低下、技术细节与创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考