Port集成同步设置Skill dot-ai-port-setup

---

name: dot-ai-port-setup description: 设置Port集成以同步Kubernetes资源和GitHub Actions到Port.io user-invocable: true

设置Port集成

设置Port集成以同步Kubernetes资源和GitHub Actions到Port.io。

先决条件

检查以下项，并指导用户安装/配置如果缺失：

• kubectl - 已安装并配置集群访问权限
• helm - 已安装（用于检查图表版本）
• gh - GitHub CLI已安装并认证
• 环境变量 设置：
  • PORT_CLIENT_ID
  • PORT_CLIENT_SECRET

通用指南

• 始终检查最新版本的第三方工具（Helm图表、GitHub Actions等）在创建清单之前。使用helm search repo或检查官方文档。
• 咨询Port MCP工具当有疑问时 - 使用它们来探索现有的蓝图、实体、操作和集成。
• 验证每个步骤在移动到下一步之前 - 验证资源被创建、同步并正常工作。
• 用户操作与自动化：一些步骤需要用户操作（标记为“需要用户操作”） - 将这些作为指令呈现，然后停止并等待用户确认在继续下一步之前。

---

步骤0：发现环境

在开始之前，发现可用工具并收集配置：

1. GitOps工具：检查ArgoCD（argocd命名空间）或Flux（flux-system命名空间）
2. ESO：检查External Secrets Operator CRD和可用的ClusterSecretStores
3. 清单目录：询问用户清单应存储在哪里（例如，apps/、manifests/、k8s/）

GitOps工具	部署方法	自助服务操作
ArgoCD	Git中的ArgoCD应用程序清单	提交YAML到Git → ArgoCD同步
Flux	Git中的Flux HelmRelease/Kustomization	提交YAML到Git → Flux同步
无	Git中的清单 + kubectl apply	提交YAML到Git → kubectl apply

ESO状态	秘密方法
安装了ClusterSecretStore	使用ExternalSecret从秘密管理器拉取
未安装	直接用kubectl create secret创建Secret

注意： 无论GitOps可用性如何，始终将清单存储在Git中以便审计。

GitOps工作流规则

重要：当检测到ArgoCD或Flux时，切勿在应用程序清单上运行kubectl apply。

相反，遵循此工作流：

1. 将清单写入Git - 在清单目录中创建YAML文件
2. 提交和推送 - GitOps工具将检测更改并自动同步
3. 验证同步状态 - 使用kubectl get applications -n argocd（ArgoCD）或flux get all（Flux）

对于GitOps资源（ArgoCD应用程序、Flux Kustomizations/HelmReleases）：

• 通过检查集群中的现有资源来发现部署模式
• 将新清单添加到适当的监视目录，以便GitOps自动同步它们

对于没有ESO的秘密：

• 直接用kubectl create secret（秘密不能以未加密形式存储在Git中）

---

第1部分：Kubernetes导出器

步骤1：创建Port凭据Secret

在port-k8s-exporter命名空间中创建一个名为port-credentials的Secret，密钥为PORT_CLIENT_ID和PORT_CLIENT_SECRET。

• 有ESO时：创建一个ExternalSecret引用可用的ClusterSecretStore
• 没有ESO时：直接用kubectl create secret创建Secret

步骤2：部署K8s导出器

从https://port-labs.github.io/helm-charts部署port-k8s-exporter Helm图表。

关键Helm值：

• secret.useExistingSecret: true 和 secret.name: port-credentials
• overwriteConfigurationOnRestart: true（强制使用configMap配置）
• stateKey 和 extraEnv[].CLUSTER_NAME 设置为集群标识符
• configMap.config 带有资源映射（见步骤4）

基于发现的部署方法：

• ArgoCD：创建ArgoCD应用程序清单
• Flux：创建HelmRepository + HelmRelease清单
• 无：运行helm install然后提交值到Git

步骤3：在Port中创建蓝图

默认蓝图（总是由导出器创建）：

• cluster（Port概念，不是K8s资源）
• namespace（来自命名空间）
• workload（来自部署、守护进程集、有状态集）

发现并推荐：

1. 运行kubectl api-resources列出所有可用资源
2. 排除已由默认覆盖的资源（命名空间、部署、守护进程集、有状态集）
3. 向用户呈现发现结果并给出建议
4. 让用户选择跟踪哪些额外资源

使用Port MCP工具创建选定的蓝图。所有蓝图应有：

• 与namespace蓝图的关系
• creationTimestamp属性

步骤4：配置资源映射

在Helm值configMap.config中，为步骤3中选择的资源定义映射。

对于嵌套资源（资源规范内的数组），使用itemsToParse：

- kind: your.api/v1/yourresource
  selector:
    query: "true"
  port:
    itemsToParse: .spec.items
    entity:
      mappings:
        - identifier: .item.name + "-" + .metadata.namespace + "-" + env.CLUSTER_NAME
          blueprint: '"child-blueprint"'
          properties:
            name: .item.name
          relations:
            Parent: .metadata.name + "-" + .metadata.namespace + "-" + env.CLUSTER_NAME

步骤5：配置蓝图关系

分析导出的资源并建立关系：

• 检查ownerReferences以链接子 → 父资源
• 使用选择器标签连接服务 → 工作负载
• 通过后端引用链接Ingress/HTTPRoute → 服务

对于每个关系：

1. 在Port中添加关系到蓝图
2. 在导出器配置中添加相应的JQ映射

---

第2部分：GitHub集成

同步GitHub工作流、工作流运行和拉取请求到Port。

步骤1：安装Port的GitHub应用（需要用户操作）

1. 转到Port的数据源：https://app.port.io/settings/data-sources
2. 点击“+ 数据源” → 选择“GitHub”
3. 在您的账户/组织上安装GitHub应用
4. 选择要同步的仓库
5. 确保权限：操作、检查、拉取请求、仓库元数据

步骤2：创建GitHub蓝图

使用Port MCP工具为githubWorkflow、githubWorkflowRun和githubPullRequest（如果不存在）创建蓝图。检查集成类型以确定适当的属性。

步骤3：配置GitHub集成映射

使用Port REST API更新集成配置，为pull-request、workflow和workflow-run类型提供映射。

步骤4：触发集成重新同步

创建蓝图后，触发重新同步以便集成用数据填充它们。使用Port API：

# 获取访问令牌
curl -s -X POST 'https://api.getport.io/v1/auth/access_token' \
  -H 'Content-Type: application/json' \
  -d '{"clientId": "'"$PORT_CLIENT_ID"'", "clientSecret": "'"$PORT_CLIENT_SECRET"'"}' \
  | jq -r '.accessToken' > ./port_access_token.txt

# 触发重新同步（将INTEGRATION_ID替换为实际ID）
curl -s -X PATCH 'https://api.getport.io/v1/integration/INTEGRATION_ID' \
  -H "Authorization: Bearer $(cat ./port_access_token.txt)" \
  -H 'Content-Type: application/json' \
  -d '{}'

# 清理
rm -f ./port_access_token.txt

从mcp__port-vscode-eu__list_integrations获取集成ID。

---

第3部分：CRD的自助服务操作

创建Port自助服务操作，触发GitHub工作流来管理CRD清单。

步骤0：配置GitHub仓库秘密

使用gh secret set添加所需秘密：

• PORT_CLIENT_ID - Port客户端ID
• PORT_CLIENT_SECRET - Port客户端秘密
• KUBE_CONFIG - （仅限非GitOps）Base64编码的kubeconfig

步骤1：创建GitHub工作流

为每个CRD创建工作流，使用workflow_dispatch触发器接受：

• action（创建/更新/删除）
• name、namespace
• 资源特定输入
• port_run_id

工作流步骤：

1. 检出仓库
2. 使用port-labs/port-github-action@v1向Port报告“运行中”状态
3. 在配置的清单目录中创建/更新/删除清单
4. 提交并推送到Git
5. 仅限非GitOps：运行kubectl apply或kubectl delete
6. 向Port报告“成功”或“失败”

步骤2：创建Port自助服务操作

使用Port MCP工具为每个CRD创建3个操作：

• 创建 - 创建新资源（无实体上下文）
• DAY-2 - 更新现有资源（有实体上下文）
• 删除 - 删除资源（有实体上下文）

关键模板表达式：

• {{ .inputs.fieldName }} - 用户输入值
• {{ .run.id }} - Port操作运行ID
• {{ .entity.identifier }} - 实体标识符（用于DAY-2/删除）
• {{ .entity.identifier | split("-") | last }} - 从标识符中提取资源名称

对于DAY-2操作，用当前实体值预填充输入：

"default": {
  "jqQuery": ".entity.properties.someField // \"default_value\""
}