KubeSphere FrontendIntegration YAML 生成指南从简化单菜单模型到规范 CRD 清单【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere本文以 KubeSphere 仓库中的frontend-integration-yamlSkill 及其配套参考文档为主体完整讲解FrontendIntegrationfrontend-forge.kubesphere.io/v1alpha1资源的创作范式开发者只需编写一个单菜单 一个或多个页面的简化 JSON 规格即可通过生成器脚本一键得到可直接kubectl apply的规范 YAML。读完本文你将掌握输入模式各字段的语义、crdTable与iframe两种页面变体、字段映射与规范化规则、校验约束并能独立完成一个可用于前端扩展集成的提交级清单。一、背景FrontendIntegration 是什么FrontendIntegration是 KubeSphere 前端扩展体系frontend-forge中的核心自定义资源用于描述前端页面如何集成进 KubeSphere 控制台菜单。它的规范形态如下apiVersion: frontend-forge.kubesphere.io/v1alpha1 kind: FrontendIntegration该资源具有以下特点可参见 frontend-forge-fi-operations/SKILL.md 与 lifecycle.md集群级资源cluster-scoped操作时不要加-n命名空间参数短名为fikubectl get fi name即可查询依赖 frontend-forge 扩展frontend-forge扩展及其 InstallPlan 必须已安装且spec.enabledtrue否则任何 FI 操作都不应进行preflight 检查kubectl get extension frontend-forge与kubectl get installplan frontend-forge -o yaml。创作理念上的关键设计是简化输入、规范输出手写spec.menus[]这种规范结构繁琐且易错因此该 Skill 引入了一个单菜单创作模型——输入只包含顶层metadata、可选的spec、一个menu和pages[]由生成器展开为规范的spec.menus[]。二、简化创作模型Input Schema生成器接受 JSON 输入可以从标准输入stdin读取也可以通过--input path指定文件。整个模型分为四个顶层字段顶层字段必填说明metadata是资源元数据核心是metadata.namespec否透传字段enabled、displayName、builder、localesmenu是单个菜单的定义displayName、icon、placementspages是一个或多个页面crdTable或iframe变体{ metadata: { name: required, annotations: { kubesphere.io/description: optional } }, spec: { enabled: true, displayName: optional, builder: { engineVersion: optional }, locales: { en: { KEY: Value } } }, menu: { displayName: required, icon: optional, defaults to GridDuotone, placements: [cluster] }, pages: [] }各字段语义与脚本实现见 generate_frontend_integration.pymetadata.name资源名称直接映射为FrontendIntegration.metadata.namemetadata.annotations可选原样保留。脚本中由sanitize_annotations()校验并清洗键和值都必须是非空字符串见normalize_metadata()spec.enabled可选默认true脚本中normalize_bool(..., defaultTrue)spec.displayName/spec.builder.engineVersion可选透传字段仅当提供时写入输出spec.locales可选的多语言文案字典格式为{en: {KEY: Value}}脚本会逐层校验所有键值均为非空字符串menu.displayName必填将作为所有展开后菜单的displayNamemenu.icon可选省略时默认使用GridDuotone脚本常量DEFAULT_MENU_ICON GridDuotonemenu.placements必填合法值为cluster、workspace、global脚本常量VALID_PLACEMENTS且不允许重复pages必填且至少一个页面页面type只能是crdTable或iframe脚本常量VALID_PAGE_TYPES。注意 Skill 的使用边界见 SKILL.md本 Skill 只负责生成 YAML不负责排查已有 FI 资源、不管理启用/禁用/删除生命周期、不检查 JSBundle/Job/controller/status 流程也不处理多菜单创作模型。这些分别属于 frontend-forge-fi-operations 等 Skill 的职责。三、页面变体crdTable 与 iframe3.1 crdTable以 CRD 数据驱动的表格页crdTable页面会把某个 CRD 的实例以表格形式渲染到控制台{ displayName: Bundles, key: optional, type: crdTable, crdTable: { authKey: optional, group: extensions.kubesphere.io, version: v1alpha1, scope: Cluster, names: { kind: JSBundle, plural: jsbundles }, columns: [] } }字段规则必填crdTable.group、crdTable.version、crdTable.scope、crdTable.names.plural可选names.kind提供时透传key默认取names.plural脚本中normalized_key plural if key is None else keycolumns可选省略时根据scope生成默认列详见第五章authKey可选认证相关透传字段提供时透传。3.2 iframe内嵌外部页面iframe页面把外部 URL 直接内嵌为控制台页面{ displayName: Dashboard, key: dashboard, type: iframe, iframe: { src: https://example.test/dashboard } }字段规则key必填与crdTable的缺省取 plural不同iframe.src必填。crdTable与iframe是脚本VALID_PAGE_TYPES中仅有的两种页面类型若出现其他type值生成器会直接报错。四、生成器脚本的使用方式生成器脚本位于 scripts/generate_frontend_integration.py是一个零依赖的 Python 3 脚本仅使用标准库argparse/json/re/sys/pathlib通过build_parser()暴露两个参数# 从标准输入读取 JSON输出到 stdout cat spec.json | python3 skills/frontend-integration-yaml/scripts/generate_frontend_integration.py # 从文件读取 JSON输出到 stdout python3 skills/frontend-integration-yaml/scripts/generate_frontend_integration.py --input spec.json # 从文件读取 JSON输出到指定文件 python3 skills/frontend-integration-yaml/scripts/generate_frontend_integration.py --input spec.json --output fi.yamlCLI 参数说明参数默认值说明--input-JSON 创作规格的路径-或省略表示从 stdin 读取--outputstdout生成 YAML 的写入路径省略时输出到标准输出脚本主流程main()→build_canonical_resource()读取输入 → JSON 解析parse_input()→ 逐层规范化 → 组装规范资源 → 序列化为 YAML。任何ValidationError、TypeError或OSError都会以Error: message形式打印到 stderr 并返回退出码 1。值得留意的是脚本内置了一套YAML 安全序列化器dump_yaml()/format_string()/needs_quotes()字符串值若命中 YAML 保留字null、true、false、yes、no、on、off等、数字形态含十六进制、科学计数法、inf/nan、首尾空白、控制字符或无法被普通字符模式匹配时会自动用 JSON 字符串形式加引号转义从而保证生成的 YAML 可被安全解析。五、输出形态规范 FrontendIntegration YAML无论输入如何简化生成器始终输出规范的FrontendIntegration资源形态如下apiVersion: frontend-forge.kubesphere.io/v1alpha1 kind: FrontendIntegration metadata: name: example spec: enabled: true menus: - key: example-cluster displayName: Operations icon: BoxDuotone placement: cluster type: organization children: - key: jsbundles displayName: Bundles pages: - key: jsbundles type: crdTable crdTable: group: extensions.kubesphere.io version: v1alpha1 scope: Cluster names: kind: JSBundle plural: jsbundles columns: - key: name title: NAME enableSorting: true render: type: text path: metadata.name - key: updateTime title: CREATION_TIME enableHiding: true enableSorting: true render: type: time path: metadata.creationTimestamp format: local-datetime关键结构点spec.menus[]由menu展开而来每个 placement 生成一个菜单条目key的格式固定为${metadata.name}-${placement}见脚本build_canonical_resource()例如example-cluster每个菜单条目使用type: organization其children由pages[]派生pages[].displayName成为对应菜单子项的displayNamepages[].key同时成为页面 key 与子项 keymetadata.name直接映射为资源名metadata.annotations提供时保留spec.enabled默认true。字段映射一览输入字段输出位置说明metadata.namemetadata.name资源名metadata.annotationsmetadata.annotations提供时保留spec.enabledspec.enabled默认truemenu.iconspec.menus[].icon默认GridDuotonemenu.displayName/menu.placements[]spec.menus[]每个 placement 一个菜单—spec.menus[].key${metadata.name}-${placement}—spec.menus[].type恒为organizationpages[].displayName菜单子项displayName—pages[].key页面 key 与子项 keycrdTable缺省为names.plural六、规范化规则Normalization Rules生成器不仅做字段映射还会主动修正输入中的不规范之处这是它简化创作的底气所在。6.1 Placement 规则支持的 placementcluster、workspace、global大小写不敏感统一转小写重复的 placement 会被拒绝脚本抛出menu.placements contains a duplicate placement只要任一 placement 是workspace所有crdTable.scope都会被强制改为Namespacedforce_namespaced workspace in placements因为工作空间内的资源天然是命名空间级的。6.2 Scope 规则crdTable.scope接受多种写法见脚本normalize_scope()集群级Cluster、cluster→ 规范化为Cluster命名空间级Namespaced、namespaced、Namespace、namespace→ 规范化为Namespaced其他值一律报错。6.3 默认列Default Columns省略columns时生成器根据最终 scope 生成默认列。Cluster 范围两列columns: - enableSorting: true key: name render: path: metadata.name type: text title: NAME - enableHiding: true enableSorting: true key: updateTime render: format: local-datetime path: metadata.creationTimestamp type: time title: CREATION_TIMENamespaced 范围三列中间插入 PROJECT 列columns: - enableSorting: true key: name render: path: metadata.name type: text title: NAME - enableHiding: true key: namespace render: path: metadata.namespace type: text title: PROJECT - enableHiding: true enableSorting: true key: updateTime render: format: local-datetime path: metadata.creationTimestamp type: time title: CREATION_TIME6.4 自定义列的规范化如果显式提供了columns生成器会对它们做namespace 列修正脚本normalize_columns()首先移除所有已存在的namespace列若最终 scope 是Cluster直接返回剩余列即 namespace 列必然不存在若最终 scope 是Namespaced按以下优先级插入一个标准 namespace 列title: PROJECT、path: metadata.namespace存在updateTime列时插在updateTime之前否则存在name列时插在name之后否则追加到末尾。自定义列本身也要通过校验脚本validate_column()每列必须提供key、title与renderrender.type只能是text、time、link脚本常量VALID_RENDER_TYPESrender.path必填format、pattern、link、payload可选透传enableSorting/enableHiding必须是布尔值。七、校验规则Validation Rules生成器在规范化过程中会拒绝以下非法输入对应ValidationError非法情形错误提示摘录缺少metadata.namemetadata.name must be a non-empty string缺少menu.displayName或menu.placementsmenu.displayName must be .../menu.placements must contain at least one placementplacement 重复menu.placements contains a duplicate placement页面 key 重复pages contains a duplicate keycrdTable必填字段缺失pages[].crdTable.group must be a non-empty string等缺少iframe.srcpages[].iframe.src must be a non-empty string非法scopepages[].crdTable.scope must be one of Cluster, Namespace, or Namespaced非法typepages[].type must be one of crdTable, iframe非法 render 类型...render.type must be one of link, text, time输入不是合法 JSONInput must be valid JSON: ...八、完整示例8.1 仅 CRD 表格CRD Table Only输入{ metadata: { name: bundles }, menu: { displayName: Extensions, icon: BoxDuotone, placements: [cluster] }, pages: [ { displayName: Bundles, type: crdTable, crdTable: { group: extensions.kubesphere.io, version: v1alpha1, scope: Cluster, names: { kind: JSBundle, plural: jsbundles } } } ] }生成结果要点输出规范的FrontendIntegration资源menus[0].key bundles-cluster${name}-${placement}页面 key 从names.plural派生为jsbundles因为 scope 是Cluster且未提供columns自动生成 Cluster 默认列NAME CREATION_TIME。8.2 CRD 表格 iframe 混合Mixed CRD And Iframe输入{ metadata: { name: ops }, menu: { displayName: Operations, icon: AppsGearDuotone, placements: [cluster, workspace] }, pages: [ { displayName: Bundles, type: crdTable, crdTable: { group: extensions.kubesphere.io, version: v1alpha1, scope: Cluster, names: { plural: jsbundles } } }, { displayName: Dashboard, key: dashboard, type: iframe, iframe: { src: https://example.test/dashboard } } ] }生成结果要点menu.placements展开为ops-cluster与ops-workspace两个菜单由于包含workspaceplacementCRD 页面的 scope 被强制改为Namespaced即使输入写的是Cluster相应地自动插入PROJECT/namespace列表格从 Cluster 的两列变为 Namespaced 的三列dashboardiframe 页面与jsbundles表格页面同时作为两个菜单的共同子项。九、生成后的部署与运维生成器输出的 YAML 是可直接提交submit-ready的规范清单。Skill 规定先输出生成的 YAML除非用户要求解释并且在 YAML 之后必须附上固定引导语FrontendIntegration YAML has been generated. Reply apply to deploy it directly.部署与生命周期操作遵循 frontend-forge-fi-operations 及 lifecycle.md 中的流程核心命令如下。创建仅接受完整 YAML优先kubectl applykubectl apply -f fi.yaml kubectl get fi fi-name -o yaml kubectl get fi fi-name -o jsonpath{.status.phase}{\n} kubectl get fi fi-name -o jsonpath{.status.message}{\n} kubectl get fi fi-name -o jsonpath{.status.last_build.job_ref.name}{\n} kubectl get fi fi-name -o jsonpath{.status.bundle_ref.name}{\n}更新优先编辑 YAML 后重新kubectl apply -f fi.yaml仅当用户明确需要 patch 语义时才用 patch。禁用 / 启用kubectl patch fi fi-name --typemerge -p {spec:{enabled:false}} kubectl patch fi fi-name --typemerge -p {spec:{enabled:true}}删除kubectl delete fi fi-name运维时重点检查的状态字段包括.status.phase、.status.message、.status.observed_generation、.status.observed_spec_hash、.status.last_build.job_ref.name、.status.last_build.started_at与.status.bundle_ref.name。注意FrontendIntegration是集群级资源以上命令均不需要-n参数且所有操作前都应先确认frontend-forge扩展及其 InstallPlan 已存在且spec.enabledtrue。十、使用建议与边界以生成器脚本为唯一事实来源只要脚本可用就不要手工重建规范 YAMLSkill 规则明确要求。脚本的常量和错误信息如VALID_PLACEMENTS、VALID_PAGE_TYPES、VALID_RENDER_TYPES、DEFAULT_MENU_ICON是校验与默认行为的最权威参考。不要手工编写spec.menus[]规范菜单结构应始终由menupages派生避免 key 不一致或 placement 遗漏。注意 workspace 的连锁影响一旦某个 placement 是workspace所有crdTable页面都会被强制转为命名空间级并自动出现 PROJECT 列——这是生成器主动保证控制台一致性的设计。不要添加运行时托管元数据除非用户明确要求不要在输出中添加运行时管理的字段。区分 Skill 职责生成 YAML 用本 Skill创建后的启用/禁用/删除、构建状态排查与 JSBundle 检查应交给 frontend-forge-fi-operations涉及扩展安装管理时还需参考 extension-management.md。借助这套简化输入 脚本规范化的流程你可以用几十行 JSON 快速生成结构严谨的FrontendIntegration清单将 CRD 表格页与 iframe 页面以统一、可校验的方式接入 KubeSphere 控制台从而把精力集中在页面本身而非手写复杂的菜单结构上。【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考