管理 PAC 组件

仅限管理员

本指南仅适用于 集群管理员。它涵盖了需要集群管理员权限的 PAC 组件部署、配置和维护任务。

普通用户 请参考:

  • 指南 - 设置 Git provider 集成

本指南说明如何在 Kubernetes 平台上部署、更新和卸载 Pipelines-as-Code(PAC)组件。

前提条件

在管理 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 并设置其配置:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  profile: all
  targetNamespace: tekton-pipelines  # Default namespace, you can customize this
  platforms:
    kubernetes:
      pipelinesAsCode:
        enable: true
        settings:
          application-name: Pipelines as Code CI
          hub-url: http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
          hub-catalog-type: artifacthub
          hub-catalog-name: catalog
          remote-tasks: "true"
          secret-auto-create: "true"

应用更改:

kubectl edit tektonconfig config
使用

platforms.kubernetes,而不是 platforms.openshift

operator 会拒绝 spec.platforms.openshift 下的任何内容——包括 pipelinesAsCode 和 scc——并返回校验错误。如果旧配置仍包含该子树,请在应用前将其移除。

检查派生出的 OpenShiftPipelinesAsCode CR 状态:

kubectl get openshiftpipelinesascodes.operator.tekton.dev

输出应显示 READY=True;VERSION 会随版本而变化,REASON 通常为空。

NAME                  VERSION     READY   REASON
pipelines-as-code    <version>   True

验证 PAC pod 正在运行:

kubectl get pods -n tekton-pipelines | grep pipelines-as-code

示例输出(controller、watcher 和 webhook pod 必须为 Running):

NAME                                      READY   STATUS    RESTARTS   AGE
pipelines-as-code-controller-xxxxx        1/1     Running   0          5m
pipelines-as-code-watcher-xxxxx           1/1     Running   0          5m
pipelines-as-code-webhook-xxxxx           1/1     Running   0          5m

这三个 pod(controller、watcher、webhook)都必须处于 Running 状态。

operator 如何管理 PAC

由于 TektonConfig 拥有 PAC 部署,因此会产生三个后果。这也解释了本指南其余部分的大多数“意外”现象:

  • spec.profile 必须为 all。 operator 为您创建的 TektonConfig 使用的是 all,因此通常满足这一点。在 profile: basic(手写 TektonConfig 留空该字段时应用的值)或 profile: lite 下,reconciler 会在到达 PAC 部分之前返回。pipelinesAsCode 下的内容不会生效:PAC 既不会安装也不会移除,已存在的 OpenShiftPipelinesAsCode CR 也不会被触碰。
  • OpenShiftPipelinesAsCode CR 是派生的,不是手工编写的。 在启用 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:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  targetNamespace: tekton-pipelines
  pipeline:
    options:
      disabled: false
      configMaps:
        tektoncd-enhancement-feature-flags:
          data:
            enable-pac-repository: "true"

验证 operator 已协调该 ConfigMap:

kubectl get configmap tektoncd-enhancement-feature-flags \
  -n tekton-pipelines \
  -o jsonpath='{.data.enable-pac-repository}'

期望输出:

true

配置访问

重要

PAC controller 必须能够被向其发送 webhook 事件的 Git provider 访问。在配置任何 repository 之前,请先通过以下方法之一将其暴露出去。

使用 Gateway API

使用此方法可通过 ACP Gateway API 使用域名暴露 PAC controller。

Git provider -> PAC domain -> Envoy Gateway Service -> Gateway/HTTPRoute -> pipelines-as-code-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。

kubectl get gatewayclass envoy-gateway-operator-cpaas-default
NAME                                   ACCEPTED
envoy-gateway-operator-cpaas-default   True

步骤 2:准备 LoadBalancer 地址。 Envoy Gateway Service 将创建为 type: LoadBalancer,因此 LoadBalancer Service 必须能够获取外部 IP。在 ACP 裸金属集群上,请安装并配置 Alauda Container Platform Load Balancer for MetalLB。参考:配置 MetalLB。

kubectl get ipaddresspool,l2advertisement -A

预期结果:

NAMESPACE        NAME                                    ADDRESSES
metallb-system   ipaddresspool.metallb.io/default-pool   ["192.168.1.100-192.168.1.110"]

步骤 3:创建 Gateway API 资源。 创建 gateway-api.yaml。按需替换 tekton-pipelines、envoy-gateway-operator-cpaas-default 和 pac.example.com。参考:配置 GatewayAPI Gateway 和 配置 GatewayAPI Route。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: pipelines-as-code
  gatewayClassName: envoy-gateway-operator-cpaas-default
  listeners:
    - name: http
      port: 80
      hostname: pac.example.com
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  provider:
    kubernetes:
      envoyService:
        type: LoadBalancer
      envoyDeployment:
        replicas: 1
        container:
          imageRepository: registry.alauda.cn:60080/acp/envoyproxy/envoy
          resources:
            limits:
              cpu: "1"
              memory: 1Gi
            requests:
              cpu: 100m
              memory: 256Mi
    type: Kubernetes
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  hostnames:
    - pac.example.com
  parentRefs:
    - name: pipelines-as-code
      sectionName: http
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: pipelines-as-code-controller
          port: 8080

应用该文件:

kubectl apply -f gateway-api.yaml

预期结果:

gateway.gateway.networking.k8s.io/pipelines-as-code created
envoyproxy.gateway.envoyproxy.io/pipelines-as-code created
httproute.gateway.networking.k8s.io/pipelines-as-code created

步骤 4:获取外部地址。 检查生成的 Envoy Service:

kubectl get svc -A \
  -l gateway.envoyproxy.io/owning-gateway-name=pipelines-as-code,gateway.envoyproxy.io/owning-gateway-namespace=tekton-pipelines

预期结果:

NAMESPACE                  NAME                                                 TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)
envoy-gateway-operator    envoy-tekton-pipelines-pipelines-as-code-3f8c88ad    LoadBalancer   10.96.10.20     192.168.1.100   80:32176/TCP

步骤 5:验证并获取 webhook URL。 确保 Git provider 能够解析并访问 PAC 域名。常见做法是创建一个 DNS A 记录。例如,如果 Service 的 EXTERNAL-IP 为 192.168.1.100,则创建:

Type: A
Name: pac.example.com
Value: 192.168.1.100

如果 DNS 还未就绪,或者您只想从当前机器测试路由,可以使用 curl --resolve:

EXTERNAL_IP=$(kubectl get svc -A \
  -l gateway.envoyproxy.io/owning-gateway-name=pipelines-as-code,gateway.envoyproxy.io/owning-gateway-namespace=tekton-pipelines \
  -o jsonpath='{.items[0].status.loadBalancer.ingress[0].ip}')

kubectl get gateway pipelines-as-code -n tekton-pipelines
kubectl get httproute pipelines-as-code -n tekton-pipelines -o yaml
curl -i --resolve "pac.example.com:80:${EXTERNAL_IP}" http://pac.example.com/

预期结果:

  • Service 具有一个 EXTERNAL-IP。
  • Gateway 显示 PROGRAMMED=True。
  • HTTPRoute 已被接受。
  • curl 返回 PAC controller 响应。

在该域名可从 Git provider 网络访问后,打印 URL:

WEBHOOK_URL=http://pac.example.com

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-controller Service 的 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。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  rules:
  - host: pac.example.com
    http:
      paths:
      - backend:
          service:
            name: pipelines-as-code-controller
            port:
              number: 8080
        path: /
        pathType: Prefix

应用该文件:

kubectl apply -f ingress.yaml

预期结果:

ingress.networking.k8s.io/pipelines-as-code created

步骤 3:验证 Ingress 地址。 检查 Ingress 是否具有地址:

kubectl get ingress pipelines-as-code -n tekton-pipelines

预期结果:

NAME                CLASS   HOSTS             ADDRESS         PORTS
pipelines-as-code   nginx   pac.example.com   192.168.1.100   80

步骤 4:获取 webhook URL。 确保 Git provider 能通过 Ingress 地址解析并访问 pac.example.com。然后打印 URL:

HOST=$(kubectl get ingress pipelines-as-code -n tekton-pipelines \
  -o jsonpath='{.spec.rules[0].host}')

echo "WEBHOOK_URL=http://${HOST}"

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。

kubectl create secret tls pipelines-as-code-tls \
  -n tekton-pipelines \
  --cert=tls.crt \
  --key=tls.key
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  rules:
  - host: pac.example.com
    http:
      paths:
      - backend:
          service:
            name: pipelines-as-code-controller
            port:
              number: 8080
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - pac.example.com
    secretName: pipelines-as-code-tls

配置 TLS 后,请使用 HTTPS webhook URL:

echo "WEBHOOK_URL=https://${HOST}"

使用 NodePort

创建一个 NodePort Service:

apiVersion: v1
kind: Service
metadata:
  name: pipelines-as-code-controller-nodeport
  namespace: tekton-pipelines
spec:
  ports:
    - name: http-listener
      port: 8080
      protocol: TCP
      targetPort: 8082  # PAC controller listens on port 8082
      nodePort: 30080  # Optional: specify a fixed NodePort
  selector:
    app.kubernetes.io/part-of: pipelines-as-code
    app.kubernetes.io/component: controller
  type: NodePort

重要:

  • targetPort 必须为 8082,这是 PAC controller pod 监听 webhook 事件的端口
  • port(8080)是 Service 端口(用于集群内部通信)
  • nodePort(30080)是集群外部可访问的外部端口
  • 对于 Ingress,Service 端口为 8080,它会在内部转发到 controller 的 8082 端口

从可访问的节点 IP 和生成的 NodePort 打印 URL:

NODEPORT=$(kubectl get service pipelines-as-code-controller-nodeport -n tekton-pipelines \
  -o jsonpath='{.spec.ports[?(@.name=="http-listener")].nodePort}')

NODE_IP=$(kubectl get nodes \
  -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')

echo "WEBHOOK_URL=http://${NODE_IP}:${NODEPORT}"

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 下:

设置描述默认值
application-name在 Git provider UI 中显示的名称Pipelines as Code CI
hub-urlPAC 解析远程 task 和 pipeline 注解时使用的 Hub API URLhttp://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
hub-catalog-typeHub provider 类型artifacthub
hub-catalog-namePAC 远程注解所使用的默认 Artifact Hub repository 名称catalog
remote-tasks启用远程 task 解析true
secret-auto-create自动创建 secrettrue
error-detection-from-container-logs从容器日志中检测错误。仅适用于 GitHub Appstrue
error-log-snippet显示错误日志片段true
custom-console-name在 Git provider UI 中自定义 console 链接的显示名称``(空)
custom-console-urlConsole 基础 URL。按原样使用;此 key 中不会展开模板变量``(空)
custom-console-url-pr-detailsPipelineRun 详情页的 URL 模板。支持 {{ namespace }}、{{ pr }}``(空)
custom-console-url-pr-tasklogtask 日志页的 URL 模板。支持 {{ namespace }}、{{ pr }}、{{ task }}``(空)
custom-console-url-namespacenamespace 页面的 URL 模板。支持 {{ namespace }}``(空)

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 下:

设置描述默认值
custom-console-url-namespace-varscustom-console-url-* 模板的额外模板变量,从该 run 所属 namespace 的标签或注解中解析,例如 {{ project }} 和 {{ cluster }}``(空)
replace-empty-template-vars-with-empty对于没有值的模板变量(例如 push 事件中的 {{ pull_request_number }}),用空字符串替换,而不是在 PipelineRun 中保留字面量 {{ ... }}false
enable-pull-request-number-on-push-events当推送的 commit 属于某个 pull request 时,在 push 事件中填充 {{ pull_request_number }}。仅适用于 GitHubtrue

操作示例:配置自定义 Console 链接 适用于 custom-console-url-namespace-vars,另外两个则见 在 Push 事件中配置 Pull Request 编号。

每个设置应放在哪里

这两个位置由 operator 中完全不同的代码路径处理:

  • settings 不会按您写入的方式保存。operator 的 defaulting webhook 会将您的 map 解析为上游 Pipelines as Code settings 结构体,然后再从该结构体重新生成 map。任何在该结构体中没有对应字段的 key——上面列出的每个 Alauda 扩展设置都是如此——都会被静默丢弃:TektonConfig 会失去该 key,派生的 OpenShiftPipelinesAsCode CR 看不到它,生成的 pipelines-as-code ConfigMap 也不会收到它,并且不会报告任何错误或事件。
  • 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:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  profile: all
  targetNamespace: tekton-pipelines
  platforms:
    kubernetes:
      pipelinesAsCode:
        enable: true
        options:
          disabled: false
          configMaps:
            pipelines-as-code:
              data:
                custom-console-url-namespace-vars: "project=label:cpaas.io/project,cluster=label:cpaas.io/cluster"

验证该 key 已进入 ConfigMap。这是唯一可靠的检查方式——从 settings 中读回并不能说明 PAC 已收到它:

kubectl get configmap pipelines-as-code -n tekton-pipelines \
  -o jsonpath='{.data.custom-console-url-namespace-vars}'

更新 PAC 组件

更新配置

  1. 编辑 TektonConfig CR:

    kubectl edit tektonconfig config
  2. 按需更新 settings 字段:

    spec:
      platforms:
        kubernetes:
          pipelinesAsCode:
            enable: true
            settings:
              application-name: "My Custom PAC"
              hub-url: http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
              hub-catalog-type: artifacthub
              hub-catalog-name: catalog
              remote-tasks: "true"
              error-detection-from-container-logs: "true"

    若要更改某个 Alauda 扩展设置,请改为编辑 pipelinesAsCode.options.configMaps——这些 key 在保存时会从 settings 中移除。

  3. 保存并退出。operator 会更新派生的 OpenShiftPipelinesAsCode CR,然后更新 TektonInstallerSet,并应用这些更改。

不要改为编辑派生的 OpenShiftPipelinesAsCode CR:在 profile: all 下,operator 会在下一次 reconcile 时将 settings 和 options 从 TektonConfig 重新复制回来,因此更改会丢失。请参见 operator 如何管理 PAC。

常见配置更新

本节中的示例都会更新名为 config 的 TektonConfig 中的 spec.platforms.kubernetes.pipelinesAsCode。每个示例都会显示其所属的字段——大多数使用 settings,而 Alauda 扩展设置使用 options.configMaps。如果不确定该使用哪个,请参见 每个设置应放在哪里。

kubectl edit tektonconfig config

custom-console-* 设置会重写 PAC 回传给 Git provider 的集群侧链接,使其指向平台控制台。下面的示例从 namespace 标签中解析 {{ project }} 和 {{ cluster }},因此 URL 不需要硬编码 cluster 标识符。

注意,三个带模板的 key 位于 settings 下,而 custom-console-url-namespace-vars 必须位于 options.configMaps 下——请参见 每个设置应放在哪里:

spec:
  targetNamespace: tekton-pipelines
  platforms:
    kubernetes:
      pipelinesAsCode:
        enable: true
        settings:
          custom-console-name: "My Console"
          custom-console-url: "https://console.example.com/console-acp/"
          custom-console-url-pr-details: "https://console.example.com/console-acp/workspace/{{ project }}~{{ cluster }}~{{ namespace }}/pipeline/pipelineRuns/detail/{{ pr }}"
          custom-console-url-pr-tasklog: "https://console.example.com/console-acp/workspace/{{ project }}~{{ cluster }}~{{ namespace }}/pipeline/pipelineRuns/detail/{{ pr }}?tab=task_overview&id={{ task }}"
          custom-console-url-namespace: "https://console.example.com/console-acp/workspace/{{ project }}~{{ cluster }}~{{ namespace }}/pipeline/pipelineRuns"
        options:
          disabled: false
          configMaps:
            pipelines-as-code:
              data:
                custom-console-url-namespace-vars: "project=label:cpaas.io/project,cluster=label:cpaas.io/cluster"

效果:Git provider 状态链接将打开平台控制台中的 PipelineRun 和 task 页面,而不是默认的 OpenShift 风格占位 URL。

Warning

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 在发布状态链接时会展开这些变量:

变量解析为
{{ namespace }}PipelineRun 所运行的 namespace
{{ pr }}PipelineRun 名称
{{ task }}Pipeline task 名称——即 spec.pipelineSpec.tasks 下条目的 name,而不是生成的 TaskRun 资源名称
{{ pod }} 和 {{ firstFailedStep }}Pod 名称以及第一个失败步骤的名称。仅在 custom-console-url-pr-tasklog 中使用——只有这里 PAC 会填充它们,而且由于之后不会被清空,另外两个模板会得到空值,或者得到之前 task 日志链接遗留的旧值
{{ project }} 和 {{ cluster }}在 custom-console-url-namespace-vars 中声明的 namespace 标签

标准事件变量({{ 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,这正是“链接看起来正确但从不展开”的症状。

spec:
  platforms:
    kubernetes:
      pipelinesAsCode:
        options:
          disabled: false
          configMaps:
            pipelines-as-code:
              data:
                custom-console-url-namespace-vars: "project=label:cpaas.io/project|unknown,cluster=label:cpaas.io/cluster"
INFO

namespace 标签和注解最多缓存 30 分钟,因此标签更改可能需要几分钟才会出现在生成的链接中。

对于 namespace 为 my-app、名称为 my-app-build-abc123 的 PipelineRun,如果标签为 cpaas.io/project=team-a 和 cpaas.io/cluster=prod,PAC 会生成如下链接:

https://console.example.com/console-acp/workspace/team-a~prod~my-app/pipeline/pipelineRuns/detail/my-app-build-abc123
https://console.example.com/console-acp/workspace/team-a~prod~my-app/pipeline/pipelineRuns/detail/my-app-build-abc123?tab=task_overview&id=build-task
https://console.example.com/console-acp/workspace/team-a~prod~my-app/pipeline/pipelineRuns

这些 URL 会出现在 commit status、GitHub Checks 面板和 merge request 评论中。

在 Push 事件中配置 Pull Request 编号

{{ pull_request_number }} 是一个可在 repository 中的 PipelineRun 里引用的动态变量。它在 pull request 事件中有明确的值,但在 push 事件中没有。两个 Alauda 扩展设置控制此时的行为。它们都位于 options.configMaps 下,而不是 settings 下:

spec:
  targetNamespace: tekton-pipelines
  platforms:
    kubernetes:
      pipelinesAsCode:
        enable: true
        options:
          disabled: false
          configMaps:
            pipelines-as-code:
              data:
                enable-pull-request-number-on-push-events: "true"
                replace-empty-template-vars-with-empty: "true"

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 运行时。

NOTE

此设置只影响 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 事件,这两个设置的组合如下:

enable-pull-request-number-on-push-eventsreplace-empty-template-vars-with-empty{{ pull_request_number }} 解析为
"true"(默认)"false"(默认)如果该 commit 关联了 pull request,则为该 pull request 编号;否则为字面量 {{ pull_request_number }}
"true"(默认)"true"如果该 commit 关联了 pull request,则为该 pull request 编号;否则为空字符串
"false""true"始终为空字符串,即使该 commit 关联了 pull request

该表假设没有其他内容提供该名称。名为 pull_request_number 的 Repository spec.params 条目会像其他参数一样透传;当 PAC 没有从事件本身取得该值时,模板就会解析为它。

效果:将 replace-empty-template-vars-with-empty: "true" 后,引用 {{ pull_request_number }} 的 pipeline 在 pull request 和 push 事件中都可保持不变地运行,而不会在 push 时失败。

NOTE

replace-empty-template-vars-with-empty 适用于从 repository 解析出的 PipelineRun 定义。它不影响 custom-console-url-* 模板,这些模板有各自的回退行为,详见 配置自定义 Console 链接。

更改 Application 名称

使用此设置可更改 PAC 在 Git provider 状态消息中使用的显示名称:

spec:
  platforms:
    kubernetes:
      pipelinesAsCode:
        settings:
          application-name: "New Application Name"

效果:Git provider checks、status 和 comments 会显示新的 Application 名称。这不会更改派生出的 OpenShiftPipelinesAsCode 资源名称。

启用错误检测

spec:
  platforms:
    kubernetes:
      pipelinesAsCode:
        settings:
          error-detection-from-container-logs: "true"
          error-detection-max-number-of-lines: "100"

效果:PAC 会扫描失败的 task 日志,并向 Git provider 反馈中添加一段简短的错误摘要。

更新 Hub URL

默认值已经指向集群内的 artifacthub-shim Service,因此仅当 artifacthub-shim 部署在其他 namespace 中,或者您想使用外部 Hub 时才需要设置:

spec:
  platforms:
    kubernetes:
      pipelinesAsCode:
        settings:
          # The address artifacthub-shim is installed at by default. Change only the
          # namespace if it was deployed somewhere other than artifacthub-shim-system.
          hub-url: "http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local"
          hub-catalog-type: "artifacthub"
          hub-catalog-name: "catalog"

          # Or for a Tekton Hub instance - the catalog type has to change with it,
          # otherwise PAC queries it with the Artifact Hub API
          # hub-url: "https://api.hub.tekton.dev/v1"
          # hub-catalog-type: "tekton"

效果:PAC 将从指定的 Hub API 而不是默认的集群内 shim Service 解析远程 task。

查找 artifacthub-shim service:

kubectl get svc -A | grep artifacthub-shim-api

示例输出:

artifacthub-shim-system   artifacthub-shim-api   ClusterIP   10.96.123.45   <none>   80/TCP   10m

禁用远程任务

使用 remote-tasks 控制 PAC 是否获取并嵌入由 PAC 注解引用的远程资源。

NOTE

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 处理。

spec:
  platforms:
    kubernetes:
      pipelinesAsCode:
        settings:
          remote-tasks: "false"

效果:当您希望阻止 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 对象。

spec:
  profile: all
  platforms:
    kubernetes:
      pipelinesAsCode:
        enable: false
不要手动删除派生 CR

在 profile: all 下,kubectl delete openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code 并不会在 TektonConfig 仍然启用它时卸载 PAC——下一次 reconcile 会重新创建该 CR,PAC 会恢复。应改为在 TektonConfig 中禁用它。

确认 CR、installer set 和 pod 都已消失:

kubectl get openshiftpipelinesascodes.operator.tekton.dev
kubectl get tektoninstallersets | grep pipelinesascode
kubectl get pods -n tekton-pipelines | grep pipelines-as-code

第一条命令应输出 No resources found。两个 grep 命令都不应输出任何内容——您要找的是空结果,而不是错误消息。TektonInstallerSet 是集群范围资源,因此第二条命令不需要 namespace。

清理 operator 不拥有的资源

operator 会移除其创建的一切内容。您自己添加的资源会保留,需要手动删除。

用户 namespace 中的 Repository CR:

kubectl get repositories -A
kubectl delete repositories --all -n <namespace>

用户 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 没有被其他资源使用:

kubectl delete secret <secret-name> -n <namespace>

PAC controller 的 Gateway API 资源,如果您在 配置访问 中创建过:

kubectl delete httproute pipelines-as-code -n tekton-pipelines
kubectl delete gateway pipelines-as-code -n tekton-pipelines
kubectl delete envoyproxy pipelines-as-code -n tekton-pipelines

PAC controller 的 Ingress / NodePort Service,如果您在 配置访问 中创建过:

kubectl delete ingress pipelines-as-code -n tekton-pipelines
kubectl delete service pipelines-as-code-controller-nodeport -n tekton-pipelines

故障排查

PAC Pod 未启动

检查 pod 日志:

kubectl logs -n tekton-pipelines -l app.kubernetes.io/part-of=pipelines-as-code

示例输出(示例日志条目):

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Starting PAC controller"}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"PAC controller ready"}

OpenShiftPipelinesAsCode CR 未就绪

检查派生 CR 状态和事件。这是只读检查——请在 TektonConfig 中修复配置,而不是在这里:

kubectl describe openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code

示例输出(节选):

Name:         pipelines-as-code
Namespace:
Status:       Ready
Version:      0.x.x
Events:
  Type    Reason   Age   From              Message
  ----    ------   ----  ----              -------
  Normal  Ready    5m    tekton-operator   PAC component deployed successfully

TektonInstallerSet 问题

当 TektonInstallerSet 不是 Ready 时,请读取其 conditions 以及 operator 对底层 OpenShiftPipelinesAsCode CR 的视图。两者都是只读检查;切勿自行删除 installer set。

kubectl get tektoninstallersets -o yaml
kubectl get openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code -o yaml

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:

kubectl get openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code -o yaml | grep finalizers

若存在 tekton.dev/operator finalizer,说明 operator 仍在清理;请等待后重试。若输出为空,则说明该 CR 可以自由删除。

资源未移除

当 pod 或 Service 在删除后仍然残留时:

kubectl delete deployment -n tekton-pipelines -l app.kubernetes.io/part-of=pipelines-as-code
kubectl delete service -n tekton-pipelines -l app.kubernetes.io/part-of=pipelines-as-code

下一步