/* 示例 1：Backstage 软件模板——「创建 Node.js 服务」的脚手架定义 */
/* 开发者在门户中填写表单，模板自动完成仓库创建、CI 注入、目录登记 */
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: nodejs-service-golden-path
  title: 创建 Node.js 服务（黄金路径）
  description: 按照公司标准创建一个生产就绪的 Node.js 服务
spec:
  owner: group:platform-team
  type: service
  parameters:
    - title: 服务信息
      required:
        - name
        - owner
      properties:
        name:
          title: 服务名
          type: string
          pattern: "^[a-z0-9-]+$"
          description: 小写字母、数字与连字符
        description:
          title: 服务描述
          type: string
        owner:
          title:  owning 团队
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
    - title: 部署配置
      properties:
        tier:
          title: 服务等级
          type: string
          enum: [critical, standard, experimental]
          default: standard
          description: critical 等级自动启用多可用区与更严格的 SLO
  steps:
    - id: fetch-template
      name: 拉取服务骨架
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          tier: ${{ parameters.tier }}
    - id: publish
      name: 创建 GitHub 仓库
      action: publish:github
      input:
        allowedOrganizations: ["acme"]
        repoUrl: github.com?owner=acme&repo=${{ parameters.name }}
        defaultBranch: main
    - id: register
      name: 登记到软件目录
      action: catalog:register
      input:
        repoUrl: ${{ steps.publish.output.remoteUrl }}
        catalogInfoUrl: ${{ steps.publish.output.remoteUrl }}/blob/main/catalog-info.yaml
  output:
    links:
      - title: 代码仓库
        url: ${{ steps.publish.output.remoteUrl }}
      - title: 目录条目
        icon: catalog
        entityRef: ${{ steps.register.output.entityRef }}

解释：这份 Backstage Template 是 IDP「脚手架能力」的完整实现，展示了门户层与能力层如何协作。parameters 部分定义了开发者需要填写的表单：服务名（带正则校验，从源头杜绝命名混乱）、owning 团队（OwnerPicker 组件从目录的 Group 实体中选择，保证所有权数据准确）、服务等级（tier 参数是「渐进式披露」的范例——大多数开发者用默认值 standard，只有真正关键的服务才选 critical，而 tier 会在骨架代码中驱动不同的副本数、SLO 与告警配置）。steps 部分是编排逻辑的核心：fetch:template 从骨架目录生成代码（骨架中包含 Dockerfile、CI 配置、K8s 清单、监控注册、README 与 catalog-info.yaml——即黄金路径的全部默认实践）；publish:github 创建仓库并推送；catalog:register 把新服务登记进目录，使其立即可被发现、被关联监控、被纳入治理。整个流程把传统上需要数天（复制旧仓库、手工改配置、找运维建 CI、登记 Wiki）的工作压缩为一次 2 分钟的表单提交，且产出 100% 符合规范。注意 output.links 的设计：完成后直接给出仓库与目录条目的链接，形成闭环体验。平台团队维护这份模板即维护了「创建服务的正确方式」——模板更新（如新增默认的 SBOM 生成步骤）后，所有新服务自动继承，这就是「黄金路径版本化演进」的机制基础。

/* 示例 2：Crossplane Composition——把「生产级 PostgreSQL」定义为一个复合资源 */
/* 平台团队编写一次，开发者 thereafter 只需提交一个 XPostgreSQL 申请 */
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
  name: xpostgresql-production-aws
  labels:
    platform.acme.com/tier: production
spec:
  compositeTypeRef:
    apiVersion: platform.acme.com/v1alpha1
    kind: XPostgreSQL
  resources:
    - name: rds-instance
      base:
        apiVersion: rds.aws.crossplane.io/v1alpha1
        kind: DBInstance
        spec:
          forProvider:
            dbInstanceClass: db.r6g.large
            engine: postgres
            engineVersion: "15.4"
            multiAZ: true
            storageEncrypted: true
            backupRetentionPeriod: 30
            publiclyAccessible: false
      patches:
        - fromFieldPath: spec.parameters.size
          toFieldPath: spec.forProvider.dbInstanceClass
          transforms:
            - type: map
              map:
                small: db.r6g.large
                medium: db.r6g.xlarge
                large: db.r6g.2xlarge
    - name: subnet-group
      base:
        apiVersion: rds.aws.crossplane.io/v1alpha1
        kind: DBSubnetGroup
        spec:
          forProvider:
            description: 平台管理的私有子网组
            subnetIdRefs:
              - name: platform-private-subnet-a
              - name: platform-private-subnet-b
    - name: monitoring-secret
      base:
        apiVersion: kubernetes.crossplane.io/v1alpha1
        kind: Object
        metadata:
          name: postgres-exporter-config
        spec:
          forProvider:
            manifest:
              apiVersion: v1
              kind: ConfigMap
              metadata:
                namespace: observability
              data:
                scrape-target: 由平台自动注入
---
/* 开发者侧的申请只需 12 行 */
apiVersion: platform.acme.com/v1alpha1
kind: XPostgreSQL
metadata:
  name: orders-db
  namespace: team-orders
spec:
  parameters:
    size: medium
    version: "15"

解释：这个示例展示了 IDP 基础设施层最关键的设计模式——「复合资源」（Composite Resource）。传统方式下，业务团队申请一个生产数据库需要：理解 RDS 的几十个参数、知道公司要求多可用区与加密、手工配置子网组与备份策略、再自己搭建 postgres-exporter 监控——每一步都是认知负担与出错机会。Crossplane 的 Composition 机制让平台团队把这些知识「编译」进平台：一个 Composition 声明了「当有人申请 XPostgreSQL 且标签为 production 时，创建 RDS 实例（强制 multiAZ、加密、30 天备份、私有子网）+ 子网组 + 监控配置」这一完整组合。开发者侧的接口被压缩为 12 行 YAML，唯一需要决策的是 size（三档枚举）与 version——这正是「恰到好处的抽象」：暴露必要的选择，隐藏危险的细节（publiclyAccessible: false 与 storageEncrypted: true 开发者根本无法覆盖）。patches 中的 map transform 展示了参数翻译机制：开发者说 small/medium/large（业务语言），平台翻译为具体的实例规格（基础设施语言），未来更换实例族只需改 Composition 一处。更深层的价值是「策略的不可绕过性」：因为开发者操作的是 XPostgreSQL 这个 CRD 而非 RDS 原语（RBAC 禁止业务命名空间创建 aws.crossplane.io 资源），安全基线在 API 层面就被强制执行了。这个模式可以推广到一切基础设施：XRedis、XKafkaTopic、XS3Bucket——每个复合资源都是平台团队沉淀的一份「基础设施最佳实践」。

/* 示例 3：IDP 能力层的自助环境创建工作流（Tekton Pipeline 表达） */
/* 「创建预览环境」被编排为一个原子化平台动作：建 namespace、配配额、部署、注册目录 */
apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: create-preview-environment
  namespace: platform-workflows
spec:
  params:
    - name: service-name
      type: string
    - name: team
      type: string
    - name: pr-number
      type: string
  tasks:
    - name: validate-quota
      taskRef:
        name: opa-policy-check
      params:
        - name: policy
          value: env-quota.rego
        - name: input
          value: '{"team":"$(params.team)","env":"preview"}'
    - name: provision-namespace
      runAfter: ["validate-quota"]
      taskRef:
        name: kubernetes-actions
      params:
        - name: script
          value: |
            kubectl create namespace preview-$(params.service-name)-$(params.pr-number)
            kubectl apply -f - <<EOF
            apiVersion: v1
            kind: ResourceQuota
            metadata:
              name: team-quota
              namespace: preview-$(params.service-name)-$(params.pr-number)
            spec:
              hard:
                requests.cpu: "4"
                requests.memory: 8Gi
                limits.cpu: "8"
                limits.memory: 16Gi
                pods: "20"
            EOF
    - name: deploy-service
      runAfter: ["provision-namespace"]
      taskRef:
        name: helm-upgrade
      params:
        - name: chart
          value: acme-service-chart
        - name: values
          value: |
            image.tag: pr-$(params.pr-number)
            ingress.host: $(params.service-name)-$(params.pr-number).preview.acme.io
    - name: register-in-catalog
      runAfter: ["deploy-service"]
      taskRef:
        name: http-request
      params:
        - name: url
          value: http://backstage-catalog.platform.svc/v1/entities
        - name: method
          value: POST
    - name: notify
      runAfter: ["register-in-catalog"]
      taskRef:
        name: slack-message
      params:
        - name: text
          value: "预览环境已就绪: https://$(params.service-name)-$(params.pr-number).preview.acme.io"

解释：这份 Tekton Pipeline 是 IDP 能力层「工作流编排」的具象化，它把「创建预览环境」这个开发者任务分解为五个自动化步骤并处理了它们之间的依赖与策略。逐步分析：validate-quota 首先执行 OPA 策略检查——该团队本月已创建多少预览环境？是否超过配额？策略前置意味着「审批」被自动化：符合策略立即通过，不符合立即拒绝并给出原因，无需人工介入。provision-namespace 创建独立的 K8s namespace 并施加 ResourceQuota（4 CPU/8Gi 请求上限、最多 20 个 Pod）——这是多租户隔离与成本控制的关键：预览环境是「用完即弃」的，配额防止某个 PR 的环境吞噬集群资源。deploy-service 用统一的 Helm chart 部署服务，镜像标签与 Ingress 主机名由 PR 号参数化生成，保证每个 PR 有独立的访问地址。register-in-catalog 把新环境登记到 Backstage 目录（作为 location 实体或环境的 annotation），使其在门户中可发现、可关联。notify 通过 Slack 把环境 URL 推送给开发者——体验闭环的最后一步。整个流水线由 PR 创建事件自动触发（配合 GitHub webhook），开发者提交 PR 后约 5 分钟收到可点击的预览环境链接，而在此之前这个流程需要找运维手工搭建。设计要点：每个 task 都是幂等的（重试安全）；runAfter 显式声明依赖形成 DAG；策略检查放在最前（fail fast）；所有参数来自触发事件而非人工输入。这个模式可以复制到 IDP 的每个自助动作：创建生产环境、申请数据库、轮换密钥——「任务 → 策略校验 → 多系统编排 → 通知闭环」是能力层工作流的通用骨架。

/* 示例 4：IDP 架构决策记录（ADR）——记录「目录选型」这一关键决策 */
/* 平台团队用 ADR 沉淀决策上下文，避免组织知识随人员流动而流失 */
# ADR-007: 软件目录选型
状态: 已接受
日期: 2024-03-15
决策者: 平台团队 + 架构评审委员会

## 上下文
IDP 第一阶段需要一个软件目录作为元数据中枢。候选方案：
A. 自建目录服务（PostgreSQL + REST API + React 前端）
B. Backstage 开源框架（含目录后端与插件生态）
C. 商业产品 Port（SaaS，按开发者席位计费）

评估维度：初始交付时间、三年 TCO、定制自由度、
数据主权、社区生态、团队技能匹配度。

## 分析摘要
方案 A：完全可控，但预估初始开发 9-12 个月，且需长期
维护 UI、认证、插件集成；目录是「无差异化重活」
（undifferentiated heavy lifting），自建不符合 TVP 原则。
方案 B：目录模型成熟（Component/API/System/Group 实体），
插件生态 2000+，社区活跃（CNCF 孵化）；成本在于需要
2-3 名工程师持续维护与升级，前端定制需要 React 能力
（团队具备）。数据完全自持。
方案 C：交付最快（数周），记分卡与自动化开箱即用；
但年订阅费约 15 万美元（300 开发者），元数据出域需要
安全评审，深度定制受限于产品路线图。

## 决策
选择方案 B（Backstage），理由：
1. 目录数据模型是 IDP 长期资产，需要完全的数据主权与演进自由；
2. 组织规模（300+ 工程师）足以摊薄维护成本；
3. 插件生态覆盖我们 80% 的集成需求（GitHub、ArgoCD、
   Datadog、PagerDuty 均有官方插件）；
4. 团队具备 TypeScript 能力，定制成本可接受。

## 后果
正面：数据自持、无许可费、可按需定制。
负面：需要承诺 2-3 FTE 的长期维护；升级 Backstage
主版本每季度约需 1-2 周工作量。
缓解：指定专人负责版本升级；建立插件兼容性测试套件。

## 复审触发条件
若维护成本连续两个季度超过 3 FTE，或商业产品出现
本地化部署选项，重启评估。

解释：架构决策记录（ADR）是平台团队工程文化的重要组成部分，这个示例记录了 IDP 建设中最关键的决策之一——目录选型。为什么目录选型值得如此郑重？因为如前所述，目录是 IDP 的「数据中枢」，所有后续能力都锚定在目录实体上，更换目录系统意味着重写全部集成——这是一个「单向门」决策（one-way door），应当用最高标准审慎做出。这份 ADR 展示了良好决策记录的要素：上下文明确列出候选方案与评估维度（避免「我们为什么当初选了 X」的考古式追问）；分析摘要诚实呈现每个方案的代价（自建的时间成本、商业产品的费用与数据主权问题）；决策理由与组织上下文绑定（300+ 工程师的规模、团队的 TypeScript 能力——同样的决策在不同组织可能完全不同）；后果部分不回避负面代价（2-3 FTE 的持续维护承诺）并给出缓解措施；复审触发条件把决策从「永久绑定」变为「有条件承诺」，这是成熟工程组织的标志。特别值得注意的是分析中引用的「无差异化重活」概念（来自 Amazon 的文化语言）：目录、门户 UI、认证集成这些能力在所有组织中都大同小异，自建它们消耗的工程资源本可以投入到真正差异化的能力层编排上——这个原则可以推广到 IDP 的所有选型决策：差异化能力自建，通用能力采用开源或商业方案。

/* 示例 5：IDP 统一 API 网关的路由配置——门户层背后的能力聚合 */
/* 所有平台能力通过统一 API 暴露，UI/CLI/ChatOps 共享同一后端 */
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: platform-api-routes
  namespace: platform
spec:
  parentRefs:
    - name: platform-gateway
  hostnames:
    - api.platform.acme.internal
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1/catalog
      backendRefs:
        - name: backstage-backend
          port: 7007
    - matches:
        - path:
            type: PathPrefix
            value: /v1/environments
      backendRefs:
        - name: env-orchestrator
          port: 8080
    - matches:
        - path:
            type: PathPrefix
            value: /v1/deployments
      backendRefs:
        - name: deployment-service
          port: 8080
    - matches:
        - path:
            type: PathPrefix
            value: /v1/workflows
      backendRefs:
        - name: workflow-engine
          port: 8080
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Platform-Audit
                value: "enabled"
---
/* 能力层服务的统一接口契约（OpenAPI 片段） */
openapi: 3.0.3
info:
  title: Platform Environments API
  version: 1.0.0
paths:
  /v1/environments:
    post:
      summary: 自助创建环境
      operationId: createEnvironment
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [serviceRef, type]
              properties:
                serviceRef:
                  type: string
                  example: component:default/payments-api
                type:
                  type: string
                  enum: [preview, staging, production]
                ttl:
                  type: string
                  example: 72h
                  description: 预览环境的自动回收时限
      responses:
        "202":
          description: 创建已受理（异步工作流）
          content:
            application/json:
              schema:
                type: object
                properties:
                  workflowId:
                    type: string
                  statusUrl:
                    type: string

解释：这个示例展示 IDP 门户层与能力层之间的「API-first」架构。HTTPRoute（K8s Gateway API 资源）把统一的平台 API 域名路由到不同的能力服务：/v1/catalog 到 Backstage 后端，/v1/environments 到自研的环境编排器，/v1/workflows 到工作流引擎。统一入口的价值在于：Web 门户、CLI、Slack 机器人、IDE 插件全部消费同一套 API，保证行为一致（不会出现「UI 能创建环境但 CLI 不能」的割裂）；认证、限流、审计在网关层统一实施（注意 X-Platform-Audit 头的注入）；底层服务可以独立演进甚至替换，只要 API 契约稳定。OpenAPI 片段定义了「创建环境」的接口契约，几个设计细节体现平台产品思维：serviceRef 使用 Backstage 实体引用格式（component:default/payments-api），把环境 API 与目录数据模型显式关联；type 枚举区分环境等级，不同等级触发不同的策略校验与资源规格；ttl 字段内置了「预览环境 72 小时自动回收」的成本治理机制——平台把最佳实践（临时环境必须有时限）设计进 API 而非依赖纪律；响应码 202（Accepted）+ workflowId 表明这是异步长任务，客户端通过 statusUrl 轮询或订阅事件获取进度，这是能力层工作流引擎的标准交互模式。契约先行（contract-first）的开发方式还带来额外收益：API 规范可以生成客户端 SDK、Mock 服务器与文档站点，门户团队与能力团队可以并行开发。