#管理 PAC 组件

本指南介绍如何在 Kubernetes 平台上部署、更新和卸载 Pipelines-as-Code（PAC）组件。

#前提条件

在管理 PAC 之前，请确保你具备以下条件：

• Kubernetes 集群（版本 1.24 或更高）
• 已安装并运行 Tekton Operator
• 集群管理员权限
• 已安装并配置好 kubectl 以访问你的集群

#部署 PAC 组件

通过创建 OpenShiftPipelinesAsCode CR 来部署 PAC。operator 会接收该 CR 并预配所有必需资源。

本文档中的示例使用默认 PAC 命名空间 tekton-pipelines。如果你设置了不同的 targetNamespace，请在命令和清单中将 tekton-pipelines 替换为对应值。

#步骤 1：创建 OpenShiftPipelinesAsCode CR

创建一个名为 pac.yaml 的 YAML 文件：

apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
spec:
  settings:
    application-name: Pipelines as Code CI
    hub-url: http://tekton-hub-api.tekton-pipelines:8000/v1
    remote-tasks: "true"
    secret-auto-create: "true"
  targetNamespace: tekton-pipelines  # Default namespace, you can customize this

如果命名空间不存在，请创建它：

kubectl create namespace tekton-pipelines  # Or your custom namespace name

#步骤 2：应用配置

将 CR 应用到你的集群：

kubectl apply -f pac.yaml

示例输出：

openshiftpipelinesascode.operator.tekton.dev/pipelines-as-code created

#步骤 3：验证部署

检查 OpenShiftPipelinesAsCode CR 状态：

kubectl get openshiftpipelinesascodes.operator.tekton.dev

输出应显示该 CR 处于 Ready 状态：

NAME                  VERSION   READY   REASON
pipelines-as-code    0.x.x     True    Ready

检查 TektonInstallerSet 状态：

kubectl get tektoninstallersets -n tekton-pipelines | grep pipelinesascode

示例输出：

NAME                              READY   REASON
pipelinesascode-installer-set     True    Ready

验证 PAC Pod 正在运行：

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

示例输出：

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 状态。

#配置访问

PAC 控制器必须能够被将向其发送 webhook 事件的 Git provider 访问。在配置任何仓库之前，请先通过以下方法之一对其进行暴露。

#使用 Gateway API

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

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 构建版 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 控制器响应。

当该域名可从 Git provider 网络访问后，输出 URL：

WEBHOOK_URL=http://pac.example.com

WEBHOOK_URL 即 PAC webhook URL。请在 Git provider 中注册此值，或者在 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 提供方。对于 MetalLB，请参阅 配置 MetalLB。
• 如果要了解 Gateway API 的其他选项，例如保留的 VIP、无主机路由或 HTTPS 监听器，请参阅 配置 GatewayAPI Gateway 和 配置 GatewayAPI Route。

#使用 Ingress

当集群已经有 Ingress Controller，且你希望使用 Ingress 域名暴露 PAC 控制器时，请使用此方法。

此示例使用：

• 默认 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。请在 Git provider 中注册此值，或者在 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 控制器 Pod 监听 webhook 事件的端口
• port（8080）是 Service 端口（用于集群内部通信）
• nodePort（30080）是可从集群外部访问的外部端口
• 对于 Ingress，Service 端口为 8080，它会在内部路由到控制器的 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。请在 Git provider 中注册此值，或者在 tkn pac create repo 提示输入 webhook URL 时填写它。

#配置设置

你可以通过 OpenShiftPipelinesAsCode CR 中的 settings 字段自定义 PAC 行为：

hub-url 指向 PAC 控制器在解析远程任务时查询的 Tekton Hub。默认的集群内 URL 为 http://tekton-hub-api.tekton-pipelines:8000/v1；如果 Hub 位于其他命名空间，请使用相同的 Service DNS 格式并替换为对应命名空间。

custom-console-* 设置会重写 PAC 回传给 Git provider 的集群侧链接，使其指向平台控制台，而不是 OpenShift Console。操作步骤见 配置自定义控制台链接。

#更新 PAC 组件

#更新配置

1. 编辑 OpenShiftPipelinesAsCode CR：

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

2. 按需更新 settings 字段：

   spec:
     settings:
       application-name: "My Custom PAC"
       hub-url: http://tekton-hub-api.tekton-pipelines:8000/v1
       remote-tasks: "true"
       error-detection-from-container-logs: "true"

3. 保存并退出。operator 会自动更新 TektonInstallerSet 并应用这些更改。

#常见配置更新

本节中的示例会更新名为 pipelines-as-code 的 OpenShiftPipelinesAsCode CR 的 spec.settings 字段。

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

#配置自定义控制台链接

custom-console-* 设置会重写 PAC 回传给 Git provider 的集群侧链接，使其指向平台控制台。将 console.example.com 和 my-cluster 替换为你的控制台主机和集群名称：

spec:
  targetNamespace: tekton-pipelines
  settings:
    custom-console-name: "My Console"
    custom-console-url: "https://console.example.com/console-acp/workspace/{{ namespace }}~my-cluster~{{ namespace }}/pipeline/pipelineRuns/"
    custom-console-url-pr-details: "https://console.example.com/console-acp/workspace/{{ namespace }}~my-cluster~{{ namespace }}/pipeline/pipelineRuns/detail/{{ pr }}"
    custom-console-url-pr-tasklog: "https://console.example.com/console-acp/workspace/{{ namespace }}~my-cluster~{{ namespace }}/pipeline/pipelineRuns/detail/{{ pr }}?tab=task_overview&id={{ task }}"
    custom-console-url-namespace: "https://console.example.com/console-acp/workspace/{{ namespace }}~my-cluster~{{ namespace }}/pipeline/pipelineRuns"
  options:
    configMaps:
      pipelines-as-code:
        data:
          replace-empty-template-vars-with-empty: "true"

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

PAC 在发布状态链接时会展开这些变量：

对于位于 my-app 命名空间中的、名为 my-app-build-abc123 的 PipelineRun，PAC 会生成如下链接：

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

这些 URL 会显示在提交状态、GitHub Checks 面板和 merge request 评论中。

#更改应用名称

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

spec:
  settings:
    application-name: "New Application Name"

效果：Git provider 的 checks、状态和评论将显示新的应用名称。这不会更改 OpenShiftPipelinesAsCode 资源名称。

#启用错误检测

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

效果：PAC 会扫描失败的任务日志，并在 Git provider 反馈中添加简短的错误片段。

#更新 Hub URL

如果你的 Tekton Hub 部署在其他命名空间中，或者你想使用外部 Hub：

spec:
  settings:
    # For a cluster-internal Hub in another namespace
    hub-url: "http://tekton-hub-api.devops-system:8000/v1"

    # Or for external/public Hub
    hub-url: "https://api.hub.tekton.dev/v1"

效果：PAC 将从指定的 Tekton Hub API 解析远程任务，而不是默认的集群内 Hub。

查找 Tekton Hub Service：

kubectl get svc -A | grep tekton-hub-api

示例输出：

tekton-pipelines   tekton-hub-api   ClusterIP   10.96.123.45   <none>   8000/TCP   10m

#禁用远程 Tasks

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

spec:
  settings:
    remote-tasks: "false"

效果：当你希望阻止 PAC 根据注解引用获取远程 Task 或 Pipeline 时，请使用 "false"。

#卸载 PAC 组件

#删除 OpenShiftPipelinesAsCode CR

删除该 CR 后，operator 会拆除 TektonInstallerSet 以及 operator 创建的所有 PAC Deployment、Service、ConfigMap 和 RBAC 对象。

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

确认 CR、installer set 和 Pod 都已消失：

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

这些命令都应返回 No resources found。

#清理 operator 不拥有的资源

operator 会删除它创建的所有内容。你自己添加的资源会保留，需要手动删除。

用户命名空间中的 Repository CR：

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

用户命名空间中的按仓库 Secret。这些是用户在配置仓库时创建的 Git provider 访问令牌（provider.token）和 webhook Secret（webhook.secret）。PAC 拥有的集群 Secret（带有 app.kubernetes.io/part-of=pipelines-as-code 标签）会由 operator 删除；而这些按仓库的 Secret 不会被删除。在删除前，请确认每个 Secret 没有被任何其他资源使用：

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

PAC 控制器的 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 控制器的 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 状态和事件：

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 -n tekton-pipelines -o yaml

如果错误仍然存在，请重新创建 OpenShiftPipelinesAsCode CR——operator 会从头重建 installer set。

#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

#后续步骤

• 指南
• 在 Git 中定义 PipelineRun
• 触发 Pipeline