KubeSphere 租户如何用 KubeSphere API 触发流水线运行并获取构建日志【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere如果你的角色是 KubeSphere 中的租户工作区成员、DevOps 项目管理员或运维人员而不是集群管理员你就无法访问kubesphere-devops-system命名空间里的 Jenkins Secret也不能直接调用 Jenkins API。租户触发流水线、查看构建状态和拉取构建日志的唯一入口是 KubeSphere API/kapis/devops.kubesphere.io/路径认证使用 KubeSphere 的 OAuth 令牌而不是 Jenkins 令牌。这篇文章给出这条完整路径获取 OAuth 令牌 → 确认流水线 → 触发运行 → 监控状态 → 获取构建日志。适用的前提条件你拥有一个租户账号且账号在目标 DevOps 项目的命名空间内有权限可列出、创建/编辑该命名空间内的 Pipeline你能访问 KubeSphere API 端点ks-apiserver文档示例中集群内地址为http://kubesphere-apiserver:80集群外可换成你的 KubeSphere API 入口地址客户端安装了curl和jq。注意KubeSphere DevOps 里的“DevOps 项目”实际是一个带devops.kubesphere.io/managedtrue标签的 Kubernetes 命名空间。API 路径中的namespaces/{namespace}使用项目的fullname即命名空间名如devopstestc2nj7而不是界面上显示的短名。前提获取租户 OAuth 令牌所有 API 调用都通过Authorization: Bearer头携带令牌。租户用账号密码向/oauth/token换取令牌client_id和client_secret都固定为kubesphereexport KUBESPHERE_APIhttp://kubesphere-apiserver:80 # 替换为你的 KubeSphere API 入口 export USERNAME你的租户用户名 export PASSWORD你的密码 # 用密码换取 OAuth 令牌 TOKEN_RESPONSE$(curl -s -X POST ${KUBESPHERE_API}/oauth/token \ -H Content-Type: application/x-www-form-urlencoded \ --data-urlencode grant_typepassword \ --data-urlencode username${USERNAME} \ --data-urlencode password${PASSWORD} \ --data-urlencode client_idkubesphere \ --data-urlencode client_secretkubesphere) export API_TOKEN$(echo $TOKEN_RESPONSE | jq -r .access_token)令牌有效期为 7200 秒2 小时令牌内携带用户的 RBAC 权限。后续所有请求都带上-H Authorization: Bearer ${API_TOKEN}。多集群环境下如果目标 DevOps 项目位于成员集群所有 DevOps 相关请求路径需要加/clusters/{cluster-name}/前缀例如/clusters/member-1/kapis/...。下面的命令以${CLUSTER}变量表示该段单集群主集群场景可去掉/clusters/${CLUSTER}前缀本文先给出带前缀的完整形式。确认 DevOps 项目与流水线存在先确认你能列出目标命名空间下的流水线。这是后续触发和取日志两个步骤的共同入口若此步返回 403说明账号没有该命名空间的权限或令牌已过期export DEVOPS_PROJECTdevopstestc2nj7 # 替换为你的 DevOps 项目命名空间fullname curl -s ${KUBESPHERE_API}/clusters/${CLUSTER}/kapis/devops.kubesphere.io/v1alpha3/namespaces/${DEVOPS_PROJECT}/pipelines \ -H Authorization: Bearer ${API_TOKEN} | jq -r .items[].metadata.name若返回的是命名空间内的流水线名称列表说明权限没问题。文档中的另一个常见现象按工作区查询workspaces/{workspace}/namespaces返回 0 条而按命名空间直接查却能查到——原因是工作区作用域的 API 用命名空间上的kubesphere.io/workspace标签过滤命名空间标签缺失时会被过滤掉该问题的修复需要管理员操作kubectl label。租户场景下直接用命名空间作用域的接口即可绕过。如果流水线还不存在租户可以先通过 API 创建。创建时必须带kubesphere.io/creator注解否则流水线可能不会在 KubeSphere 中正确显示export PIPELINE_NAMEmy-tenant-pipeline curl -s -X POST ${KUBESPHERE_API}/clusters/${CLUSTER}/kapis/devops.kubesphere.io/v1alpha3/namespaces/${DEVOPS_PROJECT}/pipelines \ -H Authorization: Bearer ${API_TOKEN} \ -H Content-Type: application/json \ -d { apiVersion: devops.kubesphere.io/v1alpha3, kind: Pipeline, metadata: { name: my-tenant-pipeline, namespace: ${DEVOPS_PROJECT}, annotations: { kubesphere.io/creator: ${USERNAME} } }, spec: { type: pipeline, pipeline: { name: my-tenant-pipeline, description: Pipeline created by tenant, jenkinsfile: pipeline { agent any; stages { stage(\Build\) { steps { sh \echo hello\ } } } } } } }创建后可用GET .../pipelines/${PIPELINE_NAME}回查并关注注解pipeline.devops.kubesphere.io/syncstatus——流水线必须同步到 Jenkins 后才能运行在 KubeSphere 能看到但 Jenkins 里没有就应先检查这个同步状态。通过 v1alpha3 API 触发流水线运行文档明确说明/kapis/devops.kubesphere.io/v1alpha2/的 runs 相关 API 已弃用触发运行应使用 v1alpha3 的pipelineruns端点。该端点创建一个 PipelineRun 对象KubeSphere 的控制器监听到后会触发对应的 Jenkins 构建。触发普通流水线先检查流水线是否定义了参数普通流水线没有专门的参数端点参数写在spec.pipeline.jenkinsfile的parameters {}指令里curl -s ${KUBESPHERE_API}/clusters/${CLUSTER}/kapis/devops.kubesphere.io/v1alpha3/namespaces/${DEVOPS_PROJECT}/pipelines/${PIPELINE_NAME} \ -H Authorization: Bearer ${API_TOKEN} | jq -r .spec.pipeline.jenkinsfile | grep -E parameters \{有参数时在请求体里逐个给出name和value布尔值必须是字符串true/false没有参数就传空数组。触发命令curl -s -X POST ${KUBESPHERE_API}/clusters/${CLUSTER}/kapis/devops.kubesphere.io/v1alpha3/namespaces/${DEVOPS_PROJECT}/pipelines/${PIPELINE_NAME}/pipelineruns \ -H Authorization: Bearer ${API_TOKEN} \ -H Content-Type: application/json \ -d { parameters: [ {name: PERSON, value: John Doe}, {name: TOGGLE, value: true} ] } | jq -r .metadata.name响应是一个 Kubernetes 格式的 PipelineRun 资源从.metadata.name取出运行名下文记为${RUN_NAME}。漏掉必需参数会导致构建失败或使用错误默认值所以触发前先查参数是文档强调的必做步骤。触发多分支流水线可选分支多分支流水线要求按分支构建分两步先列出已发现的分支再带?branch查询参数触发。# 列出分支 curl -s ${KUBESPHERE_API}/clusters/${CLUSTER}/kapis/devops.kubesphere.io/v1alpha3/namespaces/${DEVOPS_PROJECT}/pipelines/${PIPELINE_NAME}/branches?filteroriginpage1limit10 \ -H Authorization: Bearer ${API_TOKEN} \ -H Content-Type: application/json | jq -r .items[] | - Branch: \(.name) | Latest Run: \(.latestRun.id // N/A) | Status: \(.latestRun.result // N/A)文档示例输出仅示意格式实际以你的仓库为准- Branch: main | Latest Run: 2 | Status: SUCCESS - Branch: stone | Latest Run: 1 | Status: SUCCESS选定分支后触发BRANCH替换为上一步列出的分支名export BRANCHmain curl -s -X POST ${KUBESPHERE_API}/clusters/${CLUSTER}/kapis/devops.kubesphere.io/v1alpha3/namespaces/${DEVOPS_PROJECT}/pipelines/${PIPELINE_NAME}/pipelineruns?branch${BRANCH} \ -H Authorization: Bearer ${API_TOKEN} \ -H Content-Type: application/json \ -d {parameters:[]} | jq -r .metadata.name多分支流水线的参数定义从.../branches/${BRANCH}端点的.parameters数组获取拿到后同样放进请求体的parameters数组。分支没有被发现时可以调用仓库扫描端点强制重扫这是少数仍用 v1alpha2 的例外端点再用.../consolelog查看扫描日志# 触发扫描v1alpha2v1alpha3 不提供此端点 curl -s -X POST ${KUBESPHERE_API}/clusters/${CLUSTER}/kapis/devops.kubesphere.io/v1alpha2/namespaces/${DEVOPS_PROJECT}/pipelines/${PIPELINE_NAME}/scan \ -H Authorization: Bearer ${API_TOKEN} \ -H Content-Type: application/json \ -d {}监控运行状态触发后得到的是 PipelineRun 资源用 v1alpha3 端点查询# 列出某条流水线的全部运行 curl -s ${KUBESPHERE_API}/clusters/${CLUSTER}/kapis/devops.kubesphere.io/v1alpha3/namespaces/${DEVOPS_PROJECT}/pipelineruns?labelSelectordevops.kubesphere.io/pipeline${PIPELINE_NAME} \ -H Authorization: Bearer ${API_TOKEN} | jq .items[] | {name: .metadata.name, phase: .status.phase, creationTime: .metadata.creationTimestamp} # 查询单个运行 curl -s ${KUBESPHERE_API}/clusters/${CLUSTER}/kapis/devops.kubesphere.io/v1alpha3/namespaces/${DEVOPS_PROJECT}/pipelineruns/${RUN_NAME} \ -H Authorization: Bearer ${API_TOKEN} | jq -r {name: .metadata.name, phase: .status.phase, startTime: .status.startTime, completionTime: .status.completionTime}status.phase的取值是 Pending、Running、Succeeded、Failed、Unknownstatus.conditions给出更细的条件Succeeded、Readystatus.startTime和status.completionTime给出起止时间。等到 phase 变为Succeeded或Failed即表示本次构建结束再进入取日志步骤。获取构建日志日志端点目前仍是 v1alpha2Blue Ocean 风格路径租户可以正常访问无需 Jenkins 令牌。多分支流水线先从注解取 Jenkins 运行 ID多分支路径的日志 URL 需要 Jenkins 构建号而不是 Kubernetes PipelineRun 名。从 PipelineRun 资源的注解devops.kubesphere.io/jenkins-pipelinerun-id里取JENKINS_ID$(curl -s ${KUBESPHERE_API}/clusters/${CLUSTER}/kapis/devops.kubesphere.io/v1alpha3/namespaces/${DEVOPS_PROJECT}/pipelineruns/${RUN_NAME} \ -H Authorization: Bearer ${API_TOKEN} \ | jq -r .metadata.annotations.devops.kubesphere.io/jenkins-pipelinerun-id) echo Jenkins Run ID: $JENKINS_ID然后拉取日志。两个细节是文档标注的硬性要求?start0查询参数对租户访问是必需的URL 路径末尾的斜杠/也必须保留curl -s ${KUBESPHERE_API}/clusters/${CLUSTER}/kapis/devops.kubesphere.io/v1alpha2/namespaces/${DEVOPS_PROJECT}/pipelines/${PIPELINE_NAME}/branches/${BRANCH}/runs/${JENKINS_ID}/log/?start0 \ -H Authorization: Bearer ${API_TOKEN}普通流水线直接用运行 ID普通流水线非多分支按文档中的租户取日志方式用 v1alpha2 的 runs 路径# RUN_ID 为该次运行的编号如 1 curl -s ${KUBESPHERE_API}/kapis/devops.kubesphere.io/v1alpha2/namespaces/${DEVOPS_PROJECT}/pipelines/${PIPELINE_NAME}/runs/${RUN_ID}/log \ -H Authorization: Bearer ${API_TOKEN}文档提示控制台日志不一定立即可用需要轮询等待。判断日志就绪的方法之一文档示例轮询日志内容直到出现Finished:字样while ! curl -s ${KUBESPHERE_API}/kapis/devops.kubesphere.io/v1alpha2/namespaces/${DEVOPS_PROJECT}/pipelines/${PIPELINE_NAME}/runs/${RUN_ID}/log \ -H Authorization: Bearer ${API_TOKEN} | grep -q Finished:; do echo Waiting for logs... sleep 5 done文档中记录的一次成功示例日志结尾文档示例实际内容取决于你的 Jenkinsfile echo Hello from tenant pipeline Hello from tenant pipeline Finished: SUCCESS日志拿到后判断构建结果就看两处status.phase是否为Succeeded以及日志末尾是否为Finished: SUCCESS失败时对应 Failed/Finished: FAILURE。常见现象与租户限制以下问题判断直接来自项目文档都是租户 API 路径上会实际遇到的现象文档给出的原因与处理请求返回 403 Forbidden令牌过期或权限不足。先刷新 OAuth 令牌确认账号在目标命名空间内有权list pipelines。租户调用集群作用域的/apis/devops.kubesphere.io/.../devopsprojects一定会 403这是预期行为应改用/kapis/命名空间作用域端点PipelineRun 创建后没有触发构建检查 Pipeline 是否存在且已同步到 Jenkins查看注解pipeline.devops.kubesphere.io/syncstatus触发后构建立即失败检查是否漏了必需参数集群管理员侧可查控制器日志kubectl logs -n kubesphere-devops-system deployment/devops-controller租户通常无此权限需找管理员Agent label not foundJenkinsfile 里的agent { label xxx }与 Jenkins 实际 agent 标签不匹配需管理员核对 Jenkins 标签日志暂时取不到运行未完成或日志未持久化先确认status.phase已到终态再轮询日志租户的权限边界文档明确列出不能访问kubesphere-devops-system里的 Jenkins Secret、不能直接调 Jenkins API、不能看 Jenkins master 日志、不能 exec 进 agent Pod。因此本文整条路径全部走/kapis/端点是刻意选择而不是可选优化。两个文档中值得注意的 API 版本结论runs 状态的 v1alpha2 端点runs、runs/{run}已标记弃用监控状态请统一用 v1alpha3 的pipelineruns端点但日志端点log、仓库扫描端点scan/consolelog目前仍是 v1alpha2且日志端点要求?start0。更完整的端点表、参数类型对照String/Text/Boolean/Choice/Password和制品下载流程见仓库内的 skills/kubesphere-devops-pipeline/SKILL.md 与 skills/kubesphere-devops-tenant/SKILL.md。【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考