#PAC 核心概念

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

#什么是 Pipelines as Code？

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

• 将 pipeline 定义与代码一起存储在 Git 中
• 对 pipeline 配置进行版本控制
• 通过 Merge Request 审查 pipeline 更改
• 通过 Git 事件自动触发 pipeline

#架构概览

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

#核心组件

#1. Repository 概念

#1.1. Repository 自定义资源

Repository 自定义资源定义了 Git 仓库与 PAC controller 之间的连接。

关键字段：

• spec.url：Git 仓库 URL
• spec.git_provider：Git provider 配置（类型、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 provider 的 webhook 事件
• 从 Git 仓库获取 pipeline 定义
• 在 Kubernetes 中创建 PipelineRun 资源
• 管理 Repository CR（自定义资源）

部署：作为 Kubernetes Deployment 部署在某个 namespace 中（默认：tekton-pipelines，但可通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 进行自定义）。

#3. PAC Watcher

PAC Watcher 监控 PipelineRun 的执行，并：

• 跟踪 pipeline 状态（pending、running、success、failure）
• 将状态报告回 Git provider
• 更新 commit 状态以及 Pull Request/Merge Request 检查结果

部署：作为 Kubernetes Deployment 部署在某个 namespace 中（默认：tekton-pipelines，但可通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 进行自定义）。

#4. PAC Webhook

PAC Webhook 接收来自 Git provider 的 HTTP 请求：

• 校验 webhook 签名
• 处理 webhook payload
• 将事件转发给 PAC Controller

部署：作为 Kubernetes Service 部署，并可选择通过 Ingress/主机端口 暴露。

#工作原理

#1. Repository 注册

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

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

#2. 事件流

PAC Event Flow Diagram

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

1. Git provider 发送 webhook → PAC Webhook 接收该事件
2. Webhook 校验 → PAC 校验 webhook 签名
3. 事件处理 → PAC Controller 处理该事件
4. Repository 查找 → Controller 找到匹配的 Repository CR
5. Pipeline 获取 → Controller 从 Git 获取 pipeline 定义
6. 创建 PipelineRun → Controller 在 Kubernetes 中创建 PipelineRun
7. 状态监控 → PAC Watcher 监控 PipelineRun 执行
8. 状态报告 → Watcher 将状态报告回 Git provider

#3. Pipeline 执行

1. PAC Controller 根据 pipeline 定义创建 PipelineRun
2. Tekton Pipeline controller 获取该 PipelineRun
3. pipeline task 依次执行
4. PAC Watcher 监控执行过程
5. 状态报告回 Git provider

#平台支持

#Kubernetes

PAC 可以通过 Tekton Operator 部署到标准 Kubernetes 集群上。尽管资源名称包含 "OpenShift"，但通过一个 patch 可使 PAC controller 支持 Kubernetes。

部署：直接创建 OpenShiftPipelinesAsCode CR。

#Git Provider 集成

PAC 支持多个 Git provider，包括 GitHub、GitLab、Bitbucket Cloud 和 Bitbucket Data Center。每个 provider 都有特定的集成特性：

Webhook 配置：

• URL：PAC controller 端点
• Secret：用于校验的 webhook secret
• 事件：Push、Pull Request/Merge Request、评论

状态报告：

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

身份验证：

• 具有适当作用域的 Personal Access Token 或 App token（因 provider 而异）
• 存储在 Kubernetes Secret 中

关于特定 provider 的配置详情，请参阅：

• Configure Repository
• 文档中的 provider 专用指南

#Pipeline 定义

#文件位置

默认情况下，PAC 会在以下位置查找 pipeline 定义：

• .tekton/pipelinerun.yaml（将处理所有 .tekton/*.yaml 中的 PipelineRun manifest）
• .tekton/ 目录中的所有 .yaml 和 .yml 文件

#Pipeline 结构

PAC pipeline 是一个标准的 Tekton PipelineRun，并带有 PAC 专用的注解：

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 使用注解来确定何时触发 pipeline：

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

更多详情请参阅 Event Annotations。

#变量与上下文

PAC 提供可用于 pipeline 定义的动态变量。变量使用 {{<var>}} 格式，并在创建 PipelineRun 时由 PAC 自动展开。

更多详情请参阅 Parameterizing Commits and URLs。

#Git 上下文变量

• {{repo_url}}：仓库完整 URL
• {{revision}}：commit 的完整 SHA revision
• {{source_branch}}：事件发起所在的分支名称
• {{target_branch}}：事件目标分支名称
• {{repo_owner}}：仓库所有者
• {{repo_name}}：仓库名称

#事件上下文变量

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

#Pull Request / Merge Request 上下文变量

• {{pull_request_number}}：Pull Request 或 Merge Request 编号（仅适用于 pull_request 事件）

有关可用变量及其用法的完整列表，请参阅 Parameterizing Commits and URLs。

#Task 解析

PAC 可以自动从多个来源解析 task：

1. 本地 Task：在仓库中定义的 task
2. Tekton Hub：来自 Tekton Hub catalog 的 task
3. 远程 URL：来自远程 Git 仓库或 URL 的 task

更多详情请参阅 PAC Resolver。

#安全性考虑

#Webhook 安全

• Webhook secret 用于验证传入请求
• Secret 存储在 Kubernetes Secret 中
• Git provider 会校验 webhook 签名

#访问控制

• Repository CR 具有 namespace 作用域
• RBAC 控制谁可以创建 Repository CR
• Git provider token 具有受限作用域以确保安全

#Pipeline 权限

• PipelineRun 在指定的 namespace 中运行
• ServiceAccount 控制 pipeline 权限
• Secret 会按需挂载

#最佳实践

#1. Repository 组织

• 将 pipeline 定义保存在 .tekton/ 目录中
• 使用描述性强的 pipeline 名称
• 对所有 pipeline 更改进行版本控制

#2. 事件过滤

• 使用特定的分支模式
• 使用路径过滤来限制触发
• 分离 merge request 和 push pipeline

#3. Task 管理

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

#4. 安全

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

#故障排查

#常见问题

1. Pipeline 未触发：检查注解和分支名称
2. 未收到 webhook：验证 webhook URL 和 secret
3. 未找到 task：检查 task 引用和网络连接
4. 未报告状态：验证 Git provider token 权限

有关详细的故障排查信息，请参阅 Common Issues。

#下一步

• Quick Start - 开始使用 PAC
• Manage PAC Component - 部署并管理 PAC
• Configure Repository - 设置仓库集成
• Maintain Pipeline Code - 以代码形式定义 pipeline

#相关文档

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