manage-idp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Manage IDP

管理IDP

Create service catalog templates, self-service workflows, documentation, ADRs, and developer onboarding flows in Harness Internal Developer Portal.

在Harness内部开发者门户中创建服务目录模板、自助工作流、文档、ADR以及开发者入职流程。

Instructions

操作说明

Step 1: Establish Scope

步骤1：确定范围

Confirm the user's org and project context.

Call MCP tool: harness_list
Parameters:
  resource_type: "project"
  org_id: "<organization>"

确认用户的组织和项目上下文。

Call MCP tool: harness_list
Parameters:
  resource_type: "project"
  org_id: "<organization>"

Step 2: Identify the IDP Task

步骤2：确定IDP任务类型

Determine which IDP workflow the user needs:

Service Catalog Template -- Standardized microservice template with scaffolding, CI/CD, and observability
Self-Service Environment Provisioning -- On-demand environment creation with IaC and RBAC controls
Service Documentation -- Generate catalog-info.yaml, API docs, and architecture overviews
Architecture Decision Record (ADR) -- Structured decision documentation
Developer Onboarding -- Automated Day 1 onboarding workflow

明确用户需要的IDP工作流类型：

服务目录模板 —— 包含脚手架、CI/CD和可观测性的标准化微服务模板
自助环境配置 —— 基于IaC和RBAC控制的按需环境创建
服务文档 —— 生成catalog-info.yaml、API文档和架构概述
架构决策记录（ADR） —— 结构化的决策文档
开发者入职 —— 自动化的首日入职工作流

Step 3: Create Service Catalog Template

步骤3：创建服务目录模板

Gather from the user:

Technology stack (Node.js, Java, Python, Go, etc.)
Service pattern (REST API, gRPC, event-driven, etc.)
Container registry for Docker images
Observability stack (Datadog, Prometheus, etc.)

Template components to generate:

Application scaffolding with standard dependencies
CI pipeline: build, test, security scan, Docker build and push
CD pipeline: deploy to dev, staging, production with approvals
Observability: health endpoints, metrics, structured logging, dashboards
catalog-info.yaml with ownership metadata and SLO links

Call MCP tool: harness_create
Parameters:
  resource_type: "template"
  org_id: "<organization>"
  project_id: "<project>"
  body:
    name: "<stack>-microservice-template"
    identifier: "<stack>_microservice_template"
    versionLabel: "1.0.0"
    type: "Pipeline"
    yaml: |
      template:
        name: <stack>-microservice-template
        identifier: <stack>_microservice_template
        versionLabel: "1.0.0"
        type: Pipeline
        spec:
          stages:
            - stage:
                name: Build
                type: CI
                spec:
                  # Build, test, scan, push
            - stage:
                name: Deploy Dev
                type: Deployment
                spec:
                  # Deploy to dev environment

向用户收集以下信息：

技术栈（Node.js、Java、Python、Go等）
服务模式（REST API、gRPC、事件驱动等）
Docker镜像的容器注册表
可观测性栈（Datadog、Prometheus等）

需生成的模板组件：

带有标准依赖项的应用脚手架
CI流水线：构建、测试、安全扫描、Docker构建与推送
CD流水线：部署至开发、预发布、生产环境并包含审批环节
可观测性：健康检查端点、指标、结构化日志、仪表盘
包含所有权元数据和SLO链接的catalog-info.yaml

Call MCP tool: harness_create
Parameters:
  resource_type: "template"
  org_id: "<organization>"
  project_id: "<project>"
  body:
    name: "<stack>-microservice-template"
    identifier: "<stack>_microservice_template"
    versionLabel: "1.0.0"
    type: "Pipeline"
    yaml: |
      template:
        name: <stack>-microservice-template
        identifier: <stack>_microservice_template
        versionLabel: "1.0.0"
        type: Pipeline
        spec:
          stages:
            - stage:
                name: Build
                type: CI
                spec:
                  # Build, test, scan, push
            - stage:
                name: Deploy Dev
                type: Deployment
                spec:
                  # Deploy to dev environment

Step 4: Create Self-Service Environment Provisioning

步骤4：创建自助环境配置工作流

Gather from the user:

Environment type (dev, staging, QA, ephemeral)
Cloud provider and IaC tool (Terraform, Pulumi, CloudFormation)
Max concurrent environments per developer
TTL for ephemeral environments

Design the workflow with:

Pre-approved infrastructure modules
Database provisioning with test data seeding
Secret injection from Harness Secrets or Vault
RBAC: developer can create/destroy own environments
Cost controls: TTL-based auto-cleanup, budget caps

向用户收集以下信息：

环境类型（开发、预发布、QA、临时环境）
云服务商和IaC工具（Terraform、Pulumi、CloudFormation）
每位开发者可拥有的最大并发环境数
临时环境的TTL（存活时间）

设计包含以下内容的工作流：

预批准的基础设施模块
带有测试数据填充的数据库配置
从Harness Secrets或Vault注入密钥
RBAC：开发者可创建/销毁自己的环境
成本控制：基于TTL的自动清理、预算上限

Step 5: Generate Service Documentation

步骤5：生成服务文档

When asked to create documentation, gather:

Service name, team, type (backend, frontend, data pipeline)
Tech stack, repo URL, environments
API endpoints and dependencies

Generate:

catalog-info.yaml -- Backstage-compatible service registration
API documentation -- Endpoint inventory with request/response schemas
Architecture overview -- Component diagram, data flow, dependencies
Operational guide -- Deployment, monitoring, incident response links

当被要求创建文档时，收集以下信息：

服务名称、所属团队、类型（后端、前端、数据流水线）
技术栈、代码库URL、环境信息
API端点和依赖项

生成以下内容：

catalog-info.yaml —— 兼容Backstage的服务注册文件
API文档 —— 包含请求/响应 schema 的端点清单
架构概述 —— 组件图、数据流、依赖关系
操作指南 —— 部署、监控、事件响应相关链接

Step 6: Create Architecture Decision Record (ADR)

步骤6：创建架构决策记录（ADR）

Gather from the user:

Decision title and context
Options considered with pros/cons
Decision made and rationale
Consequences and follow-up actions

Format as standard ADR:

Status (Proposed, Accepted, Deprecated, Superseded)
Context, Decision, Consequences sections
Link to related ADRs if applicable

向用户收集以下信息：

决策标题和背景
已考虑的选项及其优缺点
最终决策及理由
影响和后续行动

按照标准ADR格式整理：

状态（提议、已接受、已弃用、已取代）
背景、决策、影响部分
如有相关ADR，添加链接

Step 7: Design Developer Onboarding Workflow

步骤7：设计开发者入职工作流

Gather from the user:

New engineer's role, team, and tech stack
Required access (repos, environments, tools)
Mentorship and buddy program details

Design a self-service onboarding workflow with:

Access provisioning (GitHub org, Harness project, cloud accounts)
CDE setup with pre-configured workspace
First task assignment with guided walkthrough
Week 1 and Week 2 milestone checklists

向用户收集以下信息：

新工程师的角色、团队和技术栈
所需权限（代码库、环境、工具）
导师制和伙伴计划详情

设计包含以下内容的自助入职工作流：

权限配置（GitHub组织、Harness项目、云账户）
预配置工作区的CDE（云开发环境）设置
带有引导式演练的首个任务分配
第1周和第2周的里程碑清单

Examples

示例

"Create a microservice template for our Node.js services" -- Generate service catalog template with CI/CD, observability, and catalog-info.yaml
"Set up self-service environments for developers" -- Create IDP workflow for on-demand environment provisioning
"Generate documentation for the checkout-service" -- Create catalog-info.yaml, API docs, and architecture overview
"Write an ADR for our migration from REST to gRPC" -- Create structured ADR with context, decision, and consequences
"Design an onboarding workflow for new backend engineers" -- Create Day 1 self-service workflow with access, CDE, and milestones

"为我们的Node.js服务创建微服务模板" —— 生成包含CI/CD、可观测性和catalog-info.yaml的服务目录模板
"为开发者设置自助环境" —— 创建用于按需环境配置的IDP工作流
"为checkout-service生成文档" —— 创建catalog-info.yaml、API文档和架构概述
"为我们从REST迁移到gRPC的方案编写ADR" —— 创建包含背景、决策和影响的结构化ADR
"为新后端工程师设计入职工作流" —— 创建包含权限配置、CDE和里程碑的首日自助工作流

Performance Notes

性能注意事项

Service catalog templates should be tested end-to-end before publishing -- a broken template degrades developer trust.
Self-service environments need cost guardrails (TTL, budget caps) to prevent cloud spend overruns.
catalog-info.yaml must conform to Backstage entity schema -- validate before registering.
ADRs should reference the IDP portal URL so they are discoverable alongside the service catalog.
Onboarding workflows should be idempotent -- re-running should not create duplicate resources.

服务目录模板在发布前应进行端到端测试——损坏的模板会降低开发者信任度。
自助环境需要成本防护措施（TTL、预算上限）以防止云支出超支。
catalog-info.yaml必须符合Backstage实体 schema——注册前需验证。
ADR应引用IDP门户URL，以便与服务目录一起被发现。
入职工作流应具备幂等性——重新运行不应创建重复资源。

Troubleshooting

故障排除

Template Not Appearing in Catalog

模板未在目录中显示

Verify the template YAML is valid and the identifier matches the directory name
Check that the template is published (not draft) and the version label is set
Confirm the user has read access to the org/project where the template lives

验证模板YAML有效且标识符与目录名称匹配
检查模板是否已发布（非草稿状态）且已设置版本标签
确认用户对模板所在的组织/项目具有读取权限

Self-Service Workflow Failing

自助工作流执行失败

Check IaC module permissions -- the service account needs create/destroy access in the target cloud
Verify secret references are resolvable in the target project scope
Check TTL cleanup jobs are not conflicting with active environments

检查IaC模块权限——服务账户需要目标云环境的创建/销毁权限
验证密钥引用在目标项目范围内可解析
检查TTL清理任务是否与活跃环境冲突

Documentation Out of Date

文档过时

Regenerate catalog-info.yaml when ownership or dependencies change
Link API docs to the CI pipeline so they auto-update on merge

当所有权或依赖关系变更时，重新生成catalog-info.yaml
将API文档链接到CI流水线，以便在代码合并时自动更新