管理 PAC 组件
本指南仅面向 集群管理员。它涵盖了 PAC 组件的部署、配置和维护任务,这些任务需要集群管理员权限。
普通用户 应参考:
- 配置仓库 - 设置 Git 提供方集成
- 维护 Pipeline 代码 - 创建和管理 pipeline
本指南说明如何在 Kubernetes 平台上部署、更新和卸载 Pipelines-as-Code (PAC) 组件。
目录
前提条件部署 PAC 组件部署 PAC 组件第 1 步:创建OpenShiftPipelinesAsCode CR第 2 步:应用配置第 3 步:验证部署配置访问使用 Ingress(HTTP)使用 Ingress(HTTPS)使用 NodePort如何获取 PAC Controller URL如果使用 Ingress如果使用 NodePorttkn pac 的自动检测配置设置更新 PAC 组件更新配置更新组件版本验证更新回滚配置常见配置更新更改 Application 名称启用错误检测更新 Hub URL禁用远程 task配置自定义 console 链接卸载 PAC 组件删除 OpenShiftPipelinesAsCode CR第 1 步:删除 CR第 2 步:验证卸载清理额外资源删除 Repository CR删除 Secret删除 Ingress/Service故障排查PAC Pods 未启动OpenShiftPipelinesAsCode CR 未就绪TektonInstallerSet 问题CR 无法删除资源未被移除下一步前提条件
在管理 PAC 之前,请确保你具备以下条件:
- Kubernetes 集群(1.24 或更高版本)
- Tekton Operator 已安装并正在运行
- 集群管理员权限
- 已安装并配置 kubectl 以访问你的集群
部署 PAC 组件
平台支持:尽管资源名称中包含 "OpenShift",PAC 仍可通过 Tekton Operator 的补丁在 Kubernetes 平台上部署,该补丁会添加 PAC controller 支持。
PAC 是通过直接创建 OpenShiftPipelinesAsCode CR 来部署的。operator 将自动创建并管理 PAC 所需的所有资源。
部署 PAC 组件
第 1 步:创建 OpenShiftPipelinesAsCode CR
创建一个名为 pac.yaml 的 YAML 文件:
重要:
- 资源名称必须是
pipelines-as-code,否则 operator 不会部署 PAC 组件。 targetNamespace字段指定 PAC 组件将部署到哪个命名空间。默认值为tekton-pipelines,但你可以使用任意命名空间名称。
如果命名空间不存在,请创建它:
第 2 步:应用配置
将 CR 应用到你的集群:
示例输出:
第 3 步:验证部署
检查 OpenShiftPipelinesAsCode CR 状态:
输出应显示该 CR 处于 Ready 状态:
检查 TektonInstallerSet 状态(将 <pac-namespace> 替换为你的实际 PAC 命名空间,默认值为 tekton-pipelines):
示例输出:
TektonInstallerSet 是 Tekton Operator 用于管理 PAC 组件安装和生命周期的内部 operator 资源。它充当模板,operator 使用它来创建和管理所有与 PAC 相关的资源(Deployments、Services、ConfigMaps、RBAC 等)。
重要:
- 你绝不要直接创建、修改或删除
TektonInstallerSet - 当你创建
OpenShiftPipelinesAsCodeCR 时,operator 会自动创建并管理它 - 你可以检查其状态以进行故障排查,但所有更改都应通过
OpenShiftPipelinesAsCodeCR 完成 - 当你删除
OpenShiftPipelinesAsCodeCR 时,operator 会自动删除TektonInstallerSet及所有相关资源
示例输出:
验证 PAC pods 是否正在运行:
示例输出:
注意:在本文档中,<pac-namespace> 或 tekton-pipelines 指 PAC 部署所在的命名空间。如果不同,请将其替换为你的实际命名空间名称。
你应该会看到三个处于 Running 状态的 pods:
pipelines-as-code-controller-*pipelines-as-code-watcher-*pipelines-as-code-webhook-*
配置访问
PAC 组件需要对外暴露,以便来自 Git 提供方的 webhook 事件能够访问它。配置 Git 提供方中的 webhook 时会使用 PAC controller URL。
重要:在配置仓库之前,你必须使用下面的方法之一暴露 PAC controller。tkn pac create repo 命令可以在 PAC controller 通过 Ingress 暴露时自动检测其 URL,但你需要先完成配置。
你可以使用以下方法之一来暴露 PAC controller:
使用 Ingress(HTTP)
如果你有域名:
- 使用你的域名配置
host字段(例如,pac.example.com) - 确保该域名可以通过 DNS 解析到你的 Ingress Controller 的 IP 地址
- 配置 DNS A 记录:
pac.example.com→<Ingress-Controller-IP>
如果你没有域名:
- 将
host字段留空,或从 Ingress 配置中删除host行 - 使用 IP 地址和端口访问 PAC:
http://<Ingress-Controller-IP>:<port> - Git 提供方(GitLab、GitHub)仍然可以向该 IP 地址发送 webhook
创建 IngressClass(如果尚不存在):
- 更多信息请参考 创建 Ingress。
创建一个 Ingress 资源(将 <pac-namespace> 替换为你的 PAC 命名空间,默认值为 tekton-pipelines):
应用 Ingress:
示例输出:
替代方案:不使用域名的 Ingress(无 host)
如果你没有域名,可以创建一个不包含 host 字段的 Ingress:
然后使用 Ingress Controller 的 IP 地址访问 PAC:
使用 Ingress(HTTPS)
TLS 证书要求:
- 你需要为你的域名准备一个有效的 TLS 证书
- 证书的 Common Name (CN) 或 Subject Alternative Name (SAN) 必须与域名匹配
- 在生产环境中,请使用来自受信任 CA(如 Let's Encrypt、DigiCert 等)的证书
域名配置:
- HTTPS Ingress 需要在
host字段中配置域名 - 确保 DNS 解析:
pac.example.com→<Ingress-Controller-IP> - 通过 IP 地址使用 HTTPS 访问可能会导致证书验证错误
首先,创建一个 TLS Secret(将 <pac-namespace> 替换为你的 PAC 命名空间,默认值为 tekton-pipelines):
然后创建一个 HTTPS Ingress(将 <pac-namespace> 替换为你的 PAC 命名空间,默认值为 tekton-pipelines):
使用 NodePort
创建一个 NodePort Service(将 <pac-namespace> 替换为你的 PAC 命名空间,默认值为 tekton-pipelines):
重要:
targetPort必须是8082,这是 PAC controller pod 监听 webhook 事件的端口port(8080)是 Service 端口(用于集群内部通信)nodePort(30080)是可从集群外部访问的外部端口- 对于 Ingress,Service 端口是 8080,它会在内部路由到 controller 的 8082 端口
获取 NodePort(将 <pac-namespace> 替换为你的 PAC 命名空间,默认值为 tekton-pipelines):
示例输出:
通过 http://<node-ip>:<node-port> 访问 PAC。
如何获取 PAC Controller URL
在暴露 PAC controller 之后,你可以使用以下方法获取 URL:
如果使用 Ingress
获取 Ingress host(将 <pac-namespace> 替换为你的 PAC 命名空间,默认值为 tekton-pipelines):
示例输出:
controller URL 将是:
- HTTP:
http://<ingress-host> - HTTPS:
https://<ingress-host>
如果使用 NodePort
获取 NodePort 和节点 IP:
示例输出:
tkn pac 的自动检测
当使用 tkn pac create repo 时,CLI 会通过以下方式自动检测 controller URL:
- 检查指向 PAC controller service 的 Ingress 资源
- 检查 LoadBalancer services
- 检查 NodePort services
- 如果都未找到,则提示你手动输入 URL
如果自动检测失败,你可以在提示时手动输入 controller URL。
如果你是普通用户,并且需要查找 PAC controller URL:
- 尝试上面的查询命令(如果你有集群访问权限)
- 如果命令无法运行或你没有权限,请联系你的 PAC 管理员获取 URL
- 管理员可以使用本节中的方法找到它
注意:controller URL 必须能够从 Git 提供方服务器访问,以便接收 webhook 事件。
配置设置
你可以通过 OpenShiftPipelinesAsCode CR 中的 settings 字段自定义 PAC 行为:
关于 hub-url 的说明:
- 默认值指向默认命名空间(
tekton-pipelines)中的集群内部 Tekton Hub service - 格式:
http://<service-name>.<namespace>:<port>/v1 - 如果 Tekton Hub 部署在不同的命名空间中,请相应调整 URL 中的命名空间
hub-url中的命名空间是 Tekton Hub 所在的命名空间,它可能与你的 PAC 命名空间(由targetNamespace指定)不同- 若要使用外部 Hub(例如公共 Tekton Hub),请设置为
https://api.hub.tekton.dev/v1 - 只有 PAC controller 需要访问此 URL
关于 custom-console-name 和 custom-console-url 的说明:
- 这些设置用于配置 Git 提供方 UI 中的自定义 console 链接
custom-console-name是自定义 console 链接的显示名称custom-console-url是自定义 console 的基础 URL(例如,Devops Console)custom-console-url-pr-details是 PR/MR 详情页的 URL 模板。支持变量:{{namespace}}、{{pipelinerun}}custom-console-url-pr-tasklog是 PR/MR task 日志页的 URL 模板。支持变量:{{namespace}}、{{pipelinerun}}、{{taskrun}}custom-console-url-namespace是命名空间页面的 URL 模板。支持变量:{{namespace}}- 它提供了一种方式,可将 Git 提供方 UI 中的 console 链接自定义为指向 Devops Console。
有关 PAC 设置的更多信息,请参阅 常见配置更新 部分。
更新 PAC 组件
更新配置
-
编辑
OpenShiftPipelinesAsCodeCR: -
根据需要更新
settings字段: -
保存并退出。operator 会自动更新 TektonInstallerSet 并应用更改。
更新组件版本
要更新 PAC 组件版本,请升级 Tekton Operator:
- 将 Tekton Operator 更新到目标版本
- operator 将自动:
- 删除旧的 TektonInstallerSet
- 使用新的 PAC 版本创建新的 TektonInstallerSet
- 使用新版本更新
OpenShiftPipelinesAsCodeCR
升级后检查版本:
验证更新
更新配置后:
-
检查
OpenShiftPipelinesAsCodeCR 状态:
示例输出:
-
检查 pods 是否正在重启(将
<pac-namespace>替换为你的 PAC 命名空间):
示例输出:
-
检查 pod 日志中是否存在错误:
示例输出:
-
验证配置是否已应用:
示例输出:
回滚配置
如果你需要回滚某次配置更改:
-
在
OpenShiftPipelinesAsCodeCR 中恢复之前的配置: -
或者从备份恢复:
在进行更改之前先创建备份:
从备份恢复:
常见配置更新
更改 Application 名称
启用错误检测
更新 Hub URL
如果你的 Tekton Hub 部署在不同的命名空间中,或者你想使用外部 Hub:
查找 Tekton Hub service:
示例输出:
禁用远程 task
配置自定义 console 链接
要将 PAC 与你的自定义 console 集成,请配置自定义 console 链接。这样 Git 提供方(GitLab、GitHub 等)中的 pipeline 状态链接就可以指向你的自定义 console。
配置示例
配置方法
第 1 步:确定你的集群名称
联系你的集群管理员以获取正确的集群名称。常见示例:
my-cluster- 通用集群名称business-1- 业务集群 1dev-cluster- 开发集群
集群名称会以 ~CLUSTER_NAME~ 的形式出现在 URL 路径中(注意波浪号字符)。
第 2 步:设置 console URL
将 custom-console-url 设置为你的 console 入口地址(末尾不要带斜杠):
https://console.example.comhttps://devops.example.com
第 3 步:配置 URL 模板
将 URL 模板中的 CLUSTER_NAME 替换为你的实际集群名称。PAC 会自动替换以下变量:
{{ namespace }}:执行 PipelineRun 的命名空间{{ pr }}:PipelineRun 名称{{ task }}:PipelineRun 中的 Task 名称
示例:完整配置
对于一个名为 my-cluster 且 console 地址为 https://console.example.com 的集群:
示例:生成的链接
当 PAC 在命名空间 my-project 中创建一个名为 my-app-build-abc123 的 PipelineRun,且包含一个名为 build-task 的 task 时:
-
PipelineRun 详情:
-
TaskRun 日志:
-
命名空间 Pipeline 列表:
这些链接会显示在你的 Git 提供方 UI 中(GitLab merge requests、GitHub pull requests 等),使开发者能够快速跳转到你的自定义 console。
卸载 PAC 组件
删除 OpenShiftPipelinesAsCode CR
第 1 步:删除 CR
示例输出:
operator 将自动:
- 删除 TektonInstallerSet(内部 operator 资源)
- 移除所有与 PAC 相关的资源(Deployments、Services、ConfigMaps 等)
- 清理 RBAC 资源
注意:TektonInstallerSet 是内部 operator 资源。你不应手动删除它。operator 会自动管理其生命周期。
第 2 步:验证卸载
检查 OpenShiftPipelinesAsCode CR 是否已删除:
验证 TektonInstallerSet 是否已删除(将 <pac-namespace> 替换为你的 PAC 命名空间):
注意:这是一个只读检查,用于验证内部 operator 资源是否已清理。不要尝试手动删除 TektonInstallerSet。
示例输出(如果删除成功,应该为空):
检查 PAC pods 是否已终止:
示例输出(如果删除成功,应该为空):
清理额外资源
卸载 PAC 后,你可能还需要清理其他资源:
删除 Repository CR
如果你为 Git 提供方集成创建了 Repository CR:
示例输出:
删除 Secret
重要:当你删除 OpenShiftPipelinesAsCode CR 时,operator 会自动清理 PAC 命名空间中带有 app.kubernetes.io/part-of=pipelines-as-code 标签的 secret。但是,你需要手动删除为 Git 提供方认证而创建的、与 Repository CR 相关的 secret。
会自动清理的 secret(位于 PAC 命名空间中):
pipelines-as-code-secret- PAC controller 的内部 secret(带有app.kubernetes.io/part-of=pipelines-as-code标签)
需要手动清理的 secret(位于 Repository CR 命名空间中):
gitlab-secret/github-secret- Git 提供方访问令牌webhook-secret- webhook 验证 secretgit-auth-secret- 私有仓库访问令牌git-ssh-secret- 仓库访问用 SSH key
要查找并删除与 Repository CR 相关的 secret:
-
列出 Repository CR 所在命名空间中的所有 secret:
-
识别 你为 PAC Repository CR 专门创建的 secret。
注意:secret 名称可能会因创建方式不同而有所差异。请仔细检查列表,以识别哪些 secret 与 PAC 相关。
-
在删除之前,请确保:
- 使用该 secret 的所有 Repository CR 都已删除
- 该 secret 没有被集群中的其他应用或资源使用
- 你已确认该 secret 可以安全移除
-
仅在你确定它不再需要时,删除该 secret:
警告:
- secret 可能会被多个 Repository CR 或其他资源共享
- 删除仍在使用中的 secret 会导致身份验证失败
- 在删除之前,请务必确认该 secret 没有在其他地方被引用
示例输出:
删除 Ingress/Service
如果你为 PAC 创建了 Ingress 或 NodePort Service(将 <pac-namespace> 替换为你的 PAC 命名空间):
示例输出:
故障排查
PAC Pods 未启动
检查 pod 日志(将 <pac-namespace> 替换为你的 PAC 命名空间):
示例输出(日志条目示例):
OpenShiftPipelinesAsCode CR 未就绪
检查 CR 状态和事件:
示例输出(节选):
TektonInstallerSet 问题
重要:TektonInstallerSet 是内部 operator 资源。如果你遇到与它相关的问题,请不要直接修改或删除它。应通过 OpenShiftPipelinesAsCode CR 进行排查。
检查 TektonInstallerSet 状态以进行故障排查(将 <pac-namespace> 替换为你的 PAC 命名空间):
如果 TektonInstallerSet 显示错误:
- 检查
OpenShiftPipelinesAsCodeCR 状态,查找底层问题 - 查看 operator 日志以获取详细错误信息
- 如有必要,删除并重新创建
OpenShiftPipelinesAsCodeCR(operator 会自动重新创建 TektonInstallerSet)
示例输出(节选):
CR 无法删除
如果 OpenShiftPipelinesAsCode CR 无法删除,请检查 finalizers:
示例输出(如果存在 finalizers):
如果没有 finalizers,输出将为空,表示该 CR 可以被删除。
如果存在 finalizers,说明 operator 可能仍在处理。请稍等片刻后重试。
资源未被移除
如果某些资源没有被自动移除:
-
检查 TektonInstallerSet 状态以进行故障排查(将
<pac-namespace>替换为你的 PAC 命名空间):注意:这是一个只读检查。
TektonInstallerSet是内部 operator 资源。不要手动删除它。 -
手动删除剩余资源: