管理 PAC 组件
本指南说明如何在 Kubernetes 平台上部署、更新和卸载 Pipelines-as-Code(PAC)组件。
目录
前提条件部署 PAC 组件operator 如何管理 PAC启用 Repository UI 功能配置访问使用 Gateway API使用 Ingress使用 NodePort配置设置标准设置Alauda 扩展设置每个设置应放在哪里更新 PAC 组件更新配置常见配置更新配置自定义 Console 链接在 Push 事件中配置 Pull Request 编号更改 Application 名称启用错误检测更新 Hub URL禁用远程任务卸载 PAC 组件在TektonConfig 中禁用 PAC清理 operator 不拥有的资源故障排查PAC Pod 未启动OpenShiftPipelinesAsCode CR 未就绪TektonInstallerSet 问题CR 未删除资源未移除下一步前提条件
在管理 PAC 之前,请确保您具备以下条件:
- Kubernetes 集群(版本 1.24 或更高)
- 已安装并运行 Tekton Operator
- 集群管理员权限
- 已安装 kubectl,并已配置为可访问您的集群
部署 PAC 组件
PAC 由 Tekton Operator 通过集群范围的名为 config 的 TektonConfig CR 部署。在默认的 spec.profile: all 下,operator 会基于它派生出一个 OpenShiftPipelinesAsCode CR,并保持该 CR 同步,因此 TektonConfig 是您唯一需要编辑的资源。本指南假设使用该 profile;在 basic 或 lite 下,operator 根本不会协调 PAC,集群中任何现有的 OpenShiftPipelinesAsCode CR 都需要您直接管理——请参见 operator 如何管理 PAC。示例使用默认 PAC 命名空间 tekton-pipelines;如果您的 TektonConfig.spec.targetNamespace 不同,请在命令和清单中替换它。
在 spec.platforms.kubernetes.pipelinesAsCode 下启用 PAC 并设置其配置:
应用更改:
platforms.kubernetes,而不是 platforms.openshift
operator 会拒绝 spec.platforms.openshift 下的任何内容——包括 pipelinesAsCode 和 scc——并返回校验错误。如果旧配置仍包含该子树,请在应用前将其移除。
检查派生出的 OpenShiftPipelinesAsCode CR 状态:
输出应显示 READY=True;VERSION 会随版本而变化,REASON 通常为空。
验证 PAC pod 正在运行:
示例输出(controller、watcher 和 webhook pod 必须为 Running):
这三个 pod(controller、watcher、webhook)都必须处于 Running 状态。
operator 如何管理 PAC
由于 TektonConfig 拥有 PAC 部署,因此会产生三个后果。这也解释了本指南其余部分的大多数“意外”现象:
spec.profile必须为all。 operator 为您创建的TektonConfig使用的是all,因此通常满足这一点。在profile: basic(手写TektonConfig留空该字段时应用的值)或profile: lite下,reconciler 会在到达 PAC 部分之前返回。pipelinesAsCode下的内容不会生效:PAC 既不会安装也不会移除,已存在的OpenShiftPipelinesAsCodeCR 也不会被触碰。OpenShiftPipelinesAsCodeCR 是派生的,不是手工编写的。 在启用 PAC 的profile: all下,operator 会创建该 CR,将 owner reference 指向TektonConfig,并在每次 reconcile 时将targetNamespace、config、settings、options和additionalPACControllers从TektonConfig复制回去。直接编辑派生 CR 中这些字段不会报错,但下一次 reconcile 会覆盖这些更改。排查问题时请读取该 CR;写入时请修改TektonConfig。- 删除派生 CR 并不会卸载 PAC。 只要
profile仍为all且 PAC 仍处于启用状态,下一次 reconcile 就会重新创建它。将enable: false才会让 operator 将其移除并保持移除状态——请参见 卸载 PAC 组件。
启用 Repository UI 功能
如果用户需要从 UI 中创建或管理 PAC Repository 资源,请在 tektoncd-enhancement-feature-flags ConfigMap 中启用 Repository UI 功能开关。PAC 即使不启用该开关也可以运行,但当未设置 "true" 的 enable-pac-repository 时,UI 会隐藏 Repository 工作流。
该 ConfigMap 由 TektonConfig 通过 spec.pipeline.options.configMaps 管理。应用以下配置;如果您的 TektonConfig.spec.targetNamespace 使用的是其他命名空间,请替换 tekton-pipelines:
验证 operator 已协调该 ConfigMap:
期望输出:
配置访问
PAC controller 必须能够被向其发送 webhook 事件的 Git provider 访问。在配置任何 repository 之前,请先通过以下方法之一将其暴露出去。
使用 Gateway API
使用此方法可通过 ACP Gateway API 使用域名暴露 PAC controller。
此示例使用:
- 默认 PAC 命名空间:
tekton-pipelines - GatewayClass:
envoy-gateway-operator-cpaas-default - 域名:
pac.example.com
步骤 1:准备 Envoy Gateway。 安装 Alauda build of Envoy Gateway 并确保默认 GatewayClass 已被接受。参考:Envoy Gateway Operator。
步骤 2:准备 LoadBalancer 地址。 Envoy Gateway Service 将创建为 type: LoadBalancer,因此 LoadBalancer Service 必须能够获取外部 IP。在 ACP 裸金属集群上,请安装并配置 Alauda Container Platform Load Balancer for MetalLB。参考:配置 MetalLB。
预期结果:
步骤 3:创建 Gateway API 资源。 创建 gateway-api.yaml。按需替换 tekton-pipelines、envoy-gateway-operator-cpaas-default 和 pac.example.com。参考:配置 GatewayAPI Gateway 和 配置 GatewayAPI Route。
应用该文件:
预期结果:
步骤 4:获取外部地址。 检查生成的 Envoy Service:
预期结果:
步骤 5:验证并获取 webhook URL。 确保 Git provider 能够解析并访问 PAC 域名。常见做法是创建一个 DNS A 记录。例如,如果 Service 的 EXTERNAL-IP 为 192.168.1.100,则创建:
如果 DNS 还未就绪,或者您只想从当前机器测试路由,可以使用 curl --resolve:
预期结果:
- Service 具有一个
EXTERNAL-IP。 - Gateway 显示
PROGRAMMED=True。 HTTPRoute已被接受。curl返回 PAC controller 响应。
在该域名可从 Git provider 网络访问后,打印 URL:
WEBHOOK_URL 是 PAC webhook URL。通过 TektonConfig 将此值记录到 pipelines-as-code-info.data.controller-url 中;请参见 获取 PAC Webhook URL。在手动配置 Git provider webhook 或 tkn pac create repo 提示输入 webhook URL 时,也请使用相同的值。
如果您改为通过 ACP ALB 或其他 Ingress Controller 暴露 PAC,请使用 使用 Ingress。
注意:
HTTPRoute会转发到现有的pipelines-as-code-controllerService 的 8080 端口;不要将其指向名为pipelines-as-code-webhook的 admission webhook Service。- 如果生成的 Envoy Service 仍然显示
EXTERNAL-IP=<pending>,请检查集群的 LoadBalancer provider。关于 MetalLB,请参见 配置 MetalLB。 - 有关 Gateway API 选项,例如保留 VIP、无主机路由或 HTTPS listener,请参见 配置 GatewayAPI Gateway 和 配置 GatewayAPI Route。
使用 Ingress
当集群已经有 Ingress Controller,并且您想通过 Ingress 域名暴露 PAC controller 时,请使用此方法。
此示例使用:
- 默认 PAC 命名空间:
tekton-pipelines - 域名:
pac.example.com
步骤 1:准备 Ingress Controller。 确保 Ingress Controller 已安装并就绪。参考:配置 Ingress。
步骤 2:创建 Ingress 资源。 创建 ingress.yaml。按需替换 tekton-pipelines 和 pac.example.com。
应用该文件:
预期结果:
步骤 3:验证 Ingress 地址。 检查 Ingress 是否具有地址:
预期结果:
步骤 4:获取 webhook URL。 确保 Git provider 能通过 Ingress 地址解析并访问 pac.example.com。然后打印 URL:
WEBHOOK_URL 是 PAC webhook URL。通过 TektonConfig 将此值记录到 pipelines-as-code-info.data.controller-url 中;请参见 获取 PAC Webhook URL。在手动配置 Git provider webhook 或 tkn pac create repo 提示输入 webhook URL 时,也请使用相同的值。
如果您没有 DNS 名称,请移除 host 字段,并改用可访问的 Ingress IP URL。
可选:启用 HTTPS。 在 tekton-pipelines 中创建 TLS Secret,并在同一个 Ingress 中添加 tls 部分。证书必须匹配 pac.example.com。
配置 TLS 后,请使用 HTTPS webhook URL:
使用 NodePort
创建一个 NodePort Service:
重要:
targetPort必须为8082,这是 PAC controller pod 监听 webhook 事件的端口port(8080)是 Service 端口(用于集群内部通信)nodePort(30080)是集群外部可访问的外部端口- 对于 Ingress,Service 端口为 8080,它会在内部转发到 controller 的 8082 端口
从可访问的节点 IP 和生成的 NodePort 打印 URL:
WEBHOOK_URL 是 PAC webhook URL。通过 TektonConfig 将此值记录到 pipelines-as-code-info.data.controller-url 中;请参见 获取 PAC Webhook URL。在手动配置 Git provider webhook 或 tkn pac create repo 提示输入 webhook URL 时,也请使用相同的值。
配置设置
PAC 配置位于 spec.platforms.kubernetes.pipelinesAsCode 下的两个不同位置:settings 和 options.configMaps。您必须使用哪一个取决于具体 key。在编辑之前,请先阅读 每个设置应放在哪里,因为写在错误位置的 key 会被丢弃且不会报错。
标准设置
这些 key 放在 pipelinesAsCode.settings 下:
hub-url 指向 PAC controller 在解析远程 task 时查询的 Hub 后端。ACP DevOps 默认将其设置为集群内的 artifacthub-shim Service。对于 Artifact Hub provider,请不要附加 /api/v1;PAC 会在内部追加该路径。
custom-console-* 设置会重写 PAC 回传给 Git provider 的集群侧链接,使其指向平台控制台而不是 OpenShift Console。操作步骤请见 配置自定义 Console 链接。
Alauda 扩展设置
这些 key 是 Alauda 在上游 Pipelines as Code 基础上的扩展。它们必须放在 pipelinesAsCode.options.configMaps 下,不能放在 pipelinesAsCode.settings 下:
操作示例:配置自定义 Console 链接 适用于 custom-console-url-namespace-vars,另外两个则见 在 Push 事件中配置 Pull Request 编号。
每个设置应放在哪里
这两个位置由 operator 中完全不同的代码路径处理:
settings不会按您写入的方式保存。operator 的 defaulting webhook 会将您的 map 解析为上游 Pipelines as Code settings 结构体,然后再从该结构体重新生成 map。任何在该结构体中没有对应字段的 key——上面列出的每个 Alauda 扩展设置都是如此——都会被静默丢弃:TektonConfig会失去该 key,派生的OpenShiftPipelinesAsCodeCR 看不到它,生成的pipelines-as-codeConfigMap 也不会收到它,并且不会报告任何错误或事件。options.configMaps由 additional-options transformer 应用,这是最后执行的 transformer,它会逐个 key 将您的条目合并到渲染出的 ConfigMap 中。之后没有任何东西会重写这个 map,因此任何 key 都会保留——包括 operator 不认识的 key。
有三点需要牢记:
- 将上游 key 放在
settings中,将 Alauda 扩展 key 放在options.configMaps中。不要无故把上游 key 移到options中:settings才是这些 key 文档化且经过校验的位置。 - 如果同一个 key 同时在两个位置设置,则
options.configMaps的值生效,因为该 transformer 会在基于 settings 渲染 ConfigMap 之后执行。 - 设置
options.disabled: true会关闭整个 transformer。此时options下的所有内容都会被忽略,包括这些设置,系统会回到静默丢弃的行为。请保持其未设置或设为false。
options.configMaps 是一个以 ConfigMap 名称为键的 map——它可以针对组件清单中的任意 ConfigMap,并且在名称不存在时创建一个。PAC 从名为 pipelines-as-code 的 ConfigMap 中读取其设置,因此这里应使用该 key:
验证该 key 已进入 ConfigMap。这是唯一可靠的检查方式——从 settings 中读回并不能说明 PAC 已收到它:
更新 PAC 组件
更新配置
-
编辑
TektonConfigCR: -
按需更新
settings字段:若要更改某个 Alauda 扩展设置,请改为编辑
pipelinesAsCode.options.configMaps——这些 key 在保存时会从settings中移除。 -
保存并退出。operator 会更新派生的
OpenShiftPipelinesAsCodeCR,然后更新 TektonInstallerSet,并应用这些更改。
不要改为编辑派生的 OpenShiftPipelinesAsCode CR:在 profile: all 下,operator 会在下一次 reconcile 时将 settings 和 options 从 TektonConfig 重新复制回来,因此更改会丢失。请参见 operator 如何管理 PAC。
常见配置更新
本节中的示例都会更新名为 config 的 TektonConfig 中的 spec.platforms.kubernetes.pipelinesAsCode。每个示例都会显示其所属的字段——大多数使用 settings,而 Alauda 扩展设置使用 options.configMaps。如果不确定该使用哪个,请参见 每个设置应放在哪里。
配置自定义 Console 链接
custom-console-* 设置会重写 PAC 回传给 Git provider 的集群侧链接,使其指向平台控制台。下面的示例从 namespace 标签中解析 {{ project }} 和 {{ cluster }},因此 URL 不需要硬编码 cluster 标识符。
注意,三个带模板的 key 位于 settings 下,而 custom-console-url-namespace-vars 必须位于 options.configMaps 下——请参见 每个设置应放在哪里:
效果:Git provider 状态链接将打开平台控制台中的 PipelineRun 和 task 页面,而不是默认的 OpenShift 风格占位 URL。
custom-console-url 不是模板
只有 custom-console-url-pr-details、custom-console-url-pr-tasklog 和 custom-console-url-namespace 会进行模板展开。PAC 会原样返回 custom-console-url,因此在其中写入 {{ ... }} 会生成损坏的链接。请保持它为普通 URL:它既是 console 入口点,也是模板 URL 构建失败时 PAC 回退使用的值。
PAC 在发布状态链接时会展开这些变量:
标准事件变量({{ revision }}、{{ repo_url }} 等)在这些模板中也可用,适用于该事件已解析出的 Repository spec.params 条目——没有名称的条目,或者未匹配到 CEL filter 的条目,都不会透传。上面列出的五个内置名称始终优先:复用这些名称的 namespace 变量或 Repository 参数会被忽略,而不会覆盖它们。
custom-console-url-namespace-vars 是一个以逗号分隔的列表。每个条目使用 name=label:<key> 或 name=annotation:<key>,并可选提供 |<default> 回退值,用于标签或注解缺失或为空时。没有默认值时,该变量会解析为空字符串,而不是保留为字面量 {{ name }}。
要实现这一点,需要满足两个条件。PAC 必须能够读取 namespace——例如,如果 Namespace GET 失败(比如 PAC controller 没有该 namespace 的权限),该次 run 就不会注入任何基于 namespace 的变量。而且它读取的 namespace 在创建 run 时是 Repository 所在 namespace,在报告最终状态时是 PipelineRun 所在 namespace;只有当通过 target-namespace 注解将 PipelineRun 路由到其他位置时,这两个才会不同。只要某个变量最终未被替换,generateURL 就会丢弃整个 URL,并回退到 custom-console-url,这正是“链接看起来正确但从不展开”的症状。
namespace 标签和注解最多缓存 30 分钟,因此标签更改可能需要几分钟才会出现在生成的链接中。
对于 namespace 为 my-app、名称为 my-app-build-abc123 的 PipelineRun,如果标签为 cpaas.io/project=team-a 和 cpaas.io/cluster=prod,PAC 会生成如下链接:
这些 URL 会出现在 commit status、GitHub Checks 面板和 merge request 评论中。
在 Push 事件中配置 Pull Request 编号
{{ pull_request_number }} 是一个可在 repository 中的 PipelineRun 里引用的动态变量。它在 pull request 事件中有明确的值,但在 push 事件中没有。两个 Alauda 扩展设置控制此时的行为。它们都位于 options.configMaps 下,而不是 settings 下:
enable-pull-request-number-on-push-events(默认 "true"):当 push 事件带有一个属于 pull request 的 commit 时,PAC 会将 {{ pull_request_number }} 设置为该 pull request 编号。如果您希望 push 事件永远不继承 pull request 编号,请将其设为 "false"——例如当 pipeline 使用该变量来判断自己是否正在为 pull request 运行时。
此设置只影响 GitHub。其他 provider 从 push 事件中永远不会填充 {{ pull_request_number }},因此在 GitLab 及其他 provider 中,push 事件的行为就像该设置为 "false" 一样。
此外,它也只会在 PAC 仍会处理的 push 事件中生效。上游的 skip-push-event-for-pr-commits 设置默认值为 "true",当推送的 commit 属于一个打开的 pull request 时,它会让 PAC 直接丢弃 GitHub push 事件——根本不会创建 PipelineRun,因此也没有变量可展开。其余情况仍会进入此设置:tag push(跳过规则从不适用);其 commit 只关联到已关闭或已合并 pull request 的 push,这通常是合并后产生的 push;以及当 skip-push-event-for-pr-commits 设为 "false" 时的所有 push 事件。
replace-empty-template-vars-with-empty(默认 "false"):控制 PAC 如何处理无法解析的模板变量。默认情况下,未解析的 {{ pull_request_number }} 会以字面量字符串 {{ pull_request_number }} 留在 PipelineRun 中,这通常会表现为一个毫无意义的参数值或校验失败。将其设为 "true" 可改为用空字符串替换未解析变量。名称以 body、headers 或 files 开头的变量会被刻意保留不变,因为它们是通过不同机制解析的。
对于 PAC 实际处理的 GitHub push 事件,这两个设置的组合如下:
该表假设没有其他内容提供该名称。名为 pull_request_number 的 Repository spec.params 条目会像其他参数一样透传;当 PAC 没有从事件本身取得该值时,模板就会解析为它。
效果:将 replace-empty-template-vars-with-empty: "true" 后,引用 {{ pull_request_number }} 的 pipeline 在 pull request 和 push 事件中都可保持不变地运行,而不会在 push 时失败。
replace-empty-template-vars-with-empty 适用于从 repository 解析出的 PipelineRun 定义。它不影响 custom-console-url-* 模板,这些模板有各自的回退行为,详见 配置自定义 Console 链接。
更改 Application 名称
使用此设置可更改 PAC 在 Git provider 状态消息中使用的显示名称:
效果:Git provider checks、status 和 comments 会显示新的 Application 名称。这不会更改派生出的 OpenShiftPipelinesAsCode 资源名称。
启用错误检测
效果:PAC 会扫描失败的 task 日志,并向 Git provider 反馈中添加一段简短的错误摘要。
更新 Hub URL
默认值已经指向集群内的 artifacthub-shim Service,因此仅当 artifacthub-shim 部署在其他 namespace 中,或者您想使用外部 Hub 时才需要设置:
效果:PAC 将从指定的 Hub API 而不是默认的集群内 shim Service 解析远程 task。
查找 artifacthub-shim service:
示例输出:
禁用远程任务
使用 remote-tasks 控制 PAC 是否获取并嵌入由 PAC 注解引用的远程资源。
remote-tasks: "true" 是默认值。PAC 可以获取由 pipelinesascode.tekton.dev/task 和 pipelinesascode.tekton.dev/pipeline 注解引用的远程资源,然后将解析后的 Task 或 Pipeline 嵌入生成的 PipelineRun 中。
remote-tasks: "false" 会禁用 PAC 基于注解的远程资源解析。Pipeline code 必须在 repository 中定义所需的 Pipeline 和 Tasks、将其内联,或者依赖集群资源。
此设置不会禁用 Tekton Pipelines 的远程 resolver 语法,例如 taskRef.resolver 或 pipelineRef.resolver;这些由 Tekton Pipelines controller 处理。
效果:当您希望阻止 PAC 从注解引用中获取远程 Task 或 Pipeline 时,请使用 "false"。
卸载 PAC 组件
本节描述 profile: all 的集群,在该集群中 operator 拥有 PAC 部署。在 profile: basic 或 lite 下,operator 根本不会协调 PAC:enable: false 不会删除任何内容,删除 OpenShiftPipelinesAsCode CR 本身就是卸载——不会有任何东西重新创建它。
在 TektonConfig 中禁用 PAC
设置 enable: false。operator 会删除派生的 OpenShiftPipelinesAsCode CR,进而清理 TektonInstallerSet 以及 operator 创建的所有 PAC Deployment、Service、ConfigMap 和 RBAC 对象。
在 profile: all 下,kubectl delete openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code 并不会在 TektonConfig 仍然启用它时卸载 PAC——下一次 reconcile 会重新创建该 CR,PAC 会恢复。应改为在 TektonConfig 中禁用它。
确认 CR、installer set 和 pod 都已消失:
第一条命令应输出 No resources found。两个 grep 命令都不应输出任何内容——您要找的是空结果,而不是错误消息。TektonInstallerSet 是集群范围资源,因此第二条命令不需要 namespace。
清理 operator 不拥有的资源
operator 会移除其创建的一切内容。您自己添加的资源会保留,需要手动删除。
用户 namespace 中的 Repository CR:
用户 namespace 中的每个 repository Secret。这些是用户在配置 repository 时创建的 Git provider 访问 token(provider.token)和 webhook secret(webhook.secret)。PAC 拥有的集群 Secret(带有 app.kubernetes.io/part-of=pipelines-as-code 标签)会由 operator 删除;这些按 repository 创建的 Secret 不会。删除前请确认每个 Secret 没有被其他资源使用:
PAC controller 的 Gateway API 资源,如果您在 配置访问 中创建过:
PAC controller 的 Ingress / NodePort Service,如果您在 配置访问 中创建过:
故障排查
PAC Pod 未启动
检查 pod 日志:
示例输出(示例日志条目):
OpenShiftPipelinesAsCode CR 未就绪
检查派生 CR 状态和事件。这是只读检查——请在 TektonConfig 中修复配置,而不是在这里:
示例输出(节选):
TektonInstallerSet 问题
当 TektonInstallerSet 不是 Ready 时,请读取其 conditions 以及 operator 对底层 OpenShiftPipelinesAsCode CR 的视图。两者都是只读检查;切勿自行删除 installer set。
TektonInstallerSet 是集群范围资源,因此第一条命令不带 namespace,并列出集群中所有 installer set;PAC 相关的名称中带有 pipelinesascode。
如果错误仍然存在,请让 operator 重建该 CR:在 profile: all 下,当 TektonConfig 仍然为 enable: true 时删除派生的 OpenShiftPipelinesAsCode CR,下一次 reconcile 会连同一个新的 installer set 一起将其重新创建。请先检查 profile——在 basic 或 lite 下不会有任何东西重新创建该 CR,删除它会永久移除 PAC。
CR 未删除
卡住的删除通常是被 operator finalizer 持有。列出 finalizer:
若存在 tekton.dev/operator finalizer,说明 operator 仍在清理;请等待后重试。若输出为空,则说明该 CR 可以自由删除。
资源未移除
当 pod 或 Service 在删除后仍然残留时: