管理 PAC 组件
仅适用于管理员
本指南仅适用于 集群管理员。它涵盖了 PAC 组件的部署、配置和维护任务,这些任务需要集群管理员权限。
普通用户 应参考:
本指南说明如何在 Kubernetes 平台上部署、更新和卸载 Pipelines-as-Code(PAC)组件。
前提条件
在管理 PAC 之前,请确保你已具备:
- Kubernetes 集群(版本 1.24 或更高)
- 已安装并运行的 Tekton Operator
- 集群管理员权限
- 已安装并配置为可访问你的集群的 kubectl
部署 PAC 组件
创建 OpenShiftPipelinesAsCode CR 来部署 PAC。示例使用默认 PAC 命名空间 tekton-pipelines;如果你设置了不同的 targetNamespace,请在命令和清单中替换它。
创建一个名为 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
将 CR 应用到你的集群:
kubectl apply -f pac.yaml
检查 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 状态。
启用 Repository UI 功能
如果用户需要从 UI 创建或管理 PAC Repository 资源,请在 tektoncd-enhancement-feature-flags ConfigMap 中启用 Repository UI 功能开关。PAC 即使不启用此开关也可以运行,但当未设置 enable-pac-repository 为 "true" 时,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}'
预期输出:
重要
PAC controller 必须能够从会向其发送 webhook 事件的 Git 提供商访问到。在配置任何 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。参考:Configure 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。参考:Configure GatewayAPI Gateway 和 Configure 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 提供商能够解析并访问 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 提供商网络访问后,输出 URL:
WEBHOOK_URL=http://pac.example.com
WEBHOOK_URL 即 PAC webhook URL。通过 OpenShiftPipelinesAsCode 或 TektonConfig 将此值记录到 pipelines-as-code-info.data.controller-url 中;请参阅 获取 PAC Webhook URL。当手动配置 Git 提供商 webhook,或 tkn pac create repo 提示输入 webhook URL 时,请使用相同的值。
如果你改为通过 ACP ALB 或其他 Ingress Controller 暴露 PAC,请使用 使用 Ingress。
注意:
使用 Ingress
当集群已经有 Ingress Controller,并且你希望通过 Ingress 域名暴露 PAC controller 时,请使用此方法。
此示例使用:
- 默认 PAC 命名空间:
tekton-pipelines
- 域名:
pac.example.com
步骤 1:准备 Ingress Controller。 确保已安装并就绪的 Ingress Controller。参考:Configure 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 提供商能够通过 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。通过 OpenShiftPipelinesAsCode 或 TektonConfig 将此值记录到 pipelines-as-code-info.data.controller-url 中;请参阅 获取 PAC Webhook URL。当手动配置 Git 提供商 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。通过 OpenShiftPipelinesAsCode 或 TektonConfig 将此值记录到 pipelines-as-code-info.data.controller-url 中;请参阅 获取 PAC Webhook URL。当手动配置 Git 提供商 webhook,或 tkn pac create repo 提示输入 webhook URL 时,请使用相同的值。
配置设置
你可以通过 OpenShiftPipelinesAsCode CR 中的 settings 字段来自定义 PAC 行为:
hub-url 指向 PAC controller 在解析远程 task 时查询的 Tekton Hub。默认的集群内 URL 是 http://tekton-hub-api.tekton-pipelines:8000/v1;如果 Hub 位于其他命名空间,请使用相同的 service DNS 格式并替换为对应命名空间。
custom-console-* 设置会重写 PAC 回传给 Git 提供商的集群侧链接,使其指向平台控制台而不是 OpenShift Console。custom-console-url-namespace-vars 可以添加从命名空间标签或注解中解析得到的变量。操作流程见 配置自定义控制台链接。
更新 PAC 组件
更新配置
-
编辑 OpenShiftPipelinesAsCode CR:
kubectl edit openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code
-
根据需要更新 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"
-
保存并退出。operator 将自动更新 TektonInstallerSet 并应用更改。
常见配置更新
本节中的示例会更新名为 pipelines-as-code 的 OpenShiftPipelinesAsCode CR 的 spec.settings 字段。
kubectl edit openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code
custom-console-* 设置会重写 PAC 回传给 Git 提供商的集群侧链接,使其指向平台控制台。下面的示例从命名空间标签中解析 {{ project }} 和 {{ cluster }},因此 URL 不需要硬编码集群标识符:
spec:
targetNamespace: tekton-pipelines
settings:
custom-console-name: "My Console"
custom-console-url-namespace-vars: "project=label:cpaas.io/project,cluster=label:cpaas.io/cluster"
custom-console-url: "https://console.example.com/console-acp/workspace/{{ project }}~{{ cluster }}~{{ namespace }}/pipeline/pipelineRuns/"
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:
configMaps:
pipelines-as-code:
data:
replace-empty-template-vars-with-empty: "true"
效果:Git 提供商的状态链接会打开平台控制台中的 PipelineRun 和 task 页面,而不是默认的 OpenShift 风格占位 URL。
PAC 在发布状态链接时会展开这些变量:
custom-console-url-namespace-vars 是一个以逗号分隔的列表。每一项使用 name=label:<key> 或 name=annotation:<key>,并且可以可选地带有 |<default> 回退值:
spec:
settings:
custom-console-url-namespace-vars: "project=label:cpaas.io/project|unknown,cluster=label:cpaas.io/cluster"
INFO
命名空间标签和注解最多会缓存 30 分钟,因此标签变更可能需要几分钟才会出现在生成的链接中。
对于命名空间 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 会出现在提交状态、GitHub Checks 面板和 merge request 评论中。
更改应用名称
使用此设置可更改 PAC 在 Git 提供商状态消息中使用的显示名称:
spec:
settings:
application-name: "New Application Name"
效果:Git 提供商的 checks、statuses 和 comments 会显示新的应用名称。这不会更改 OpenShiftPipelinesAsCode 资源名称。
启用错误检测
spec:
settings:
error-detection-from-container-logs: "true"
error-detection-max-number-of-lines: "100"
效果:PAC 会扫描失败的 task 日志,并向 Git 提供商反馈中添加一段简短的错误片段。
更新 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 解析远程 task,而不是默认的集群内 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
禁用远程 task
使用 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 代码必须在 repository 中定义所需的 Pipeline 和 Task、将它们内联,或依赖集群资源。
此设置不会禁用 Tekton Pipelines 的远程解析器语法,例如 taskRef.resolver 或 pipelineRef.resolver;这些由 Tekton Pipelines controller 处理。
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>
用户命名空间中的每个 repository Secret。这些是用户在配置 repository 时创建的 Git 提供商访问令牌(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 状态和事件:
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
后续步骤