#PAC 核心概念

本文档详细介绍了 Pipelines-as-Code（PAC）的核心概念、架构以及它如何与 Kubernetes 和 Git 提供商集成。

#什么是 Pipelines as Code？

Pipelines-as-Code（PAC）是一个组件，使您能够直接在源代码仓库中定义和管理 Tekton Pipeline 工作流。您无需在 Kubernetes 集群中维护流水线，而是可以：

• 将流水线定义与代码一起存储在 Git 中
• 对流水线配置进行版本控制
• 通过合并请求审查流水线变更
• 自动从 Git 事件触发流水线

#架构概览

PAC 由多个关键组件协同工作组成：

#核心组件

#1. 仓库概念

#1.1. Repository Custom Resource

Repository Custom Resource 定义了 Git 仓库与 PAC controller 之间的连接。

关键字段：

• spec.url：Git 仓库 URL
• spec.git_provider：Git 提供商配置（类型、URL、凭据）
• spec.webhook：Webhook 配置（用于验证的 secret）

示例：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret

#2. PAC Controller

PAC Controller 是主要组件，负责：

• 接收来自 Git 提供商的 webhook 事件
• 从 Git 仓库获取流水线定义
• 在 Kubernetes 中创建 PipelineRun 资源
• 管理 Repository CR（Custom Resources）

部署：作为 Kubernetes Deployment 部署在命名空间中（默认：tekton-pipelines，可通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 自定义）。

#3. PAC Watcher

PAC Watcher 监控 PipelineRun 执行情况：

• 跟踪流水线状态（待处理、运行中、成功、失败）
• 向 Git 提供商报告状态
• 更新提交状态和 Pull Request/Merge Request 检查

部署：作为 Kubernetes Deployment 部署在命名空间中（默认：tekton-pipelines，可通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 自定义）。

#4. PAC Webhook

PAC Webhook 接收来自 Git 提供商的 HTTP 请求：

• 验证 webhook 签名
• 处理 webhook 负载
• 将事件转发给 PAC Controller

部署：作为 Kubernetes Service 部署，可选通过 Ingress/NodePort 暴露。

#工作原理

#1. 仓库注册

当您使用 tkn pac create repo 配置仓库时：

1. 在 Kubernetes 集群中创建 Repository CR
2. 在 Git 提供商中配置指向 PAC controller 的 webhook
3. 创建包含 Git 提供商凭据的 Kubernetes Secret
4. 生成基础的 .tekton/pipelinerun.yaml 模板

#2. 事件流程

PAC 事件流程图

当发生 Git 事件（push、pull request、merge request、评论）时：

1. Git 提供商发送 webhook → PAC Webhook 接收事件
2. Webhook 验证 → PAC 验证 webhook 签名
3. 事件处理 → PAC Controller 处理事件
4. 仓库查找 → Controller 查找匹配的 Repository CR
5. 流水线获取 → Controller 从 Git 获取流水线定义
6. PipelineRun 创建 → Controller 在 Kubernetes 中创建 PipelineRun
7. 状态监控 → PAC Watcher 监控 PipelineRun 执行
8. 状态报告 → Watcher 向 Git 提供商报告状态

#3. 流水线执行

1. PAC Controller 根据流水线定义创建 PipelineRun
2. Tekton Pipeline controller 处理 PipelineRun
3. 按顺序执行流水线任务
4. PAC Watcher 监控执行过程
5. 状态反馈给 Git 提供商

#平台支持

#Kubernetes

PAC 可通过 Tekton Operator 部署在标准 Kubernetes 集群上。尽管资源名称包含 “OpenShift”，但通过补丁支持 Kubernetes 上的 PAC controller。

部署：直接创建 OpenShiftPipelinesAsCode CR。

#Git 提供商集成

PAC 支持多个 Git 提供商，包括 GitHub、GitLab、Bitbucket Cloud 和 Bitbucket Data Center。每个提供商具有特定的集成功能：

Webhook 配置：

• URL：PAC controller 端点
• Secret：Webhook 验证密钥
• 事件：Push、Pull Request/Merge Request、评论

状态报告：

• 提交状态更新
• Pull Request/Merge Request 状态检查
• 基于评论的命令

认证：

• 个人访问令牌或应用令牌，具备相应权限（因提供商而异）
• 存储于 Kubernetes Secret 中

有关提供商特定的配置详情，请参见：

• 配置仓库
• 文档中的提供商专用指南

#流水线定义

#文件位置

默认情况下，PAC 会查找以下位置的流水线定义：

• .tekton/pipelinerun.yaml（所有 .tekton/*.yaml 的 PipelineRun 清单都会被处理）
• .tekton/ 目录下的所有 .yaml 和 .yml 文件

#流水线结构

PAC 流水线是带有 PAC 特定注解的标准 Tekton PipelineRun：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: hello
      taskSpec:
        steps:
        - name: echo
          image: alpine:latest
          script: |
            echo "Hello from PAC!"

#事件注解

PAC 使用注解来确定何时触发流水线：

• pipelinesascode.tekton.dev/on-target-branch：事件目标分支（例如 "[main]" 或 "[refs/heads/main]"）
• pipelinesascode.tekton.dev/on-event：事件类型（例如 "[push]" 或 "[pull_request]"）
• pipelinesascode.tekton.dev/on-comment：基于评论命令触发

详情请参见 事件注解。

#变量与上下文

PAC 提供动态变量，可在流水线定义中使用。变量格式为 {{<var>}}，PAC 在创建 PipelineRun 时自动展开。

详情请参见 参数化提交和 URL。

#Git 上下文变量

• {{repo_url}}：仓库完整 URL
• {{revision}}：提交的完整 SHA
• {{source_branch}}：事件来源分支名
• {{target_branch}}：事件目标分支名
• {{repo_owner}}：仓库所有者
• {{repo_name}}：仓库名称

#事件上下文变量

• {{sender}}：事件发送者的用户名或账户 ID

#Pull Request / Merge Request 上下文变量

• {{pull_request_number}}：Pull Request 或 Merge Request 编号（仅对 pull_request 事件有效）

完整变量列表及用法请参见 参数化提交和 URL。

#任务解析

PAC 可自动解析多种来源的任务：

1. 本地任务：仓库中定义的任务
2. Tekton Hub：来自 Tekton Hub 目录的任务
3. 远程 URL：来自远程 Git 仓库或 URL 的任务

详情请参见 PAC Resolver。

#安全注意事项

#Webhook 安全

• 使用 webhook secret 验证传入请求
• secret 存储于 Kubernetes Secret 中
• Git 提供商验证 webhook 签名

#访问控制

• Repository CR 具有命名空间范围
• 通过 RBAC 控制谁可以创建 Repository CR
• Git 提供商令牌权限有限以保障安全

#流水线权限

• PipelineRun 在指定命名空间中运行
• 通过 ServiceAccount 控制流水线权限
• 按需挂载 Secrets

#最佳实践

#1. 仓库组织

• 将流水线定义保存在 .tekton/ 目录
• 使用描述性流水线名称
• 对所有流水线变更进行版本控制

#2. 事件过滤

• 使用特定分支模式
• 使用路径过滤限制触发
• 分离合并请求和推送流水线

#3. 任务管理

• 尽可能使用 Tekton Hub 任务
• 创建可复用的任务定义
• 对任务定义进行版本控制

#4. 安全

• 不要在流水线文件中硬编码 secret
• 使用 Kubernetes Secret
• 限制流水线权限

#故障排查

#常见问题

1. 流水线未触发：检查注解和分支名称
2. 未收到 webhook：验证 webhook URL 和 secret
3. 任务未找到：检查任务引用和网络连接
4. 状态未报告：验证 Git 提供商令牌权限

详细故障排查请参见 常见问题。

#后续步骤

• 快速开始 - 快速上手 PAC
• 管理 PAC 组件 - 部署和管理 PAC
• 配置仓库 - 设置仓库集成
• 维护流水线代码 - 在代码中定义流水线

#相关文档

• Pipeline As Code - Pipelines As Code 官方文档